mdtoc

README

mdtoc

Generate a table of contents for an existing markdown document. The table of contents will link to anchor tags, and preserve the level of nesting.

• CLI
  • Installation
  • Usage
  • Examples
• Library
  • Usage

CLI

Installation

Via go get:

go get github.com/jar-b/mdtoc/cmd/mdtoc

Usage

$ mdtoc -h
Usage: mdtoc [flags] [filename]

Flags:
  -dry-run
        print generated contents, but do not write to file (optional)
  -force
        force overwrite of existing contents (optional)
  -out string
        output file (optional, defaults to adding to source file)
  -toc-heading string
        contents heading (-with-toc-heading must be specified) (default "Table of Contents")
  -version
        display version
  -with-toc-heading
        include a heading with the generated contents (optional)

Examples

# add new
mdtoc mydoc.md

# dry run
mdtoc -dry-run mydoc.md

# force overwrite of existing
mdtoc -force mydoc.md

# redirect output to new document
mdtoc -out other.md mydoc.md

# with custom heading
mdtoc -with-toc-heading -toc-heading "document stuff" mydoc.md

Library

import github.com/jar-b/mdtoc

Usage

package main

import (
        "fmt"

        "github.com/jar-b/mdtoc"
)

func main() {
        b := []byte("# Title\ndescription text\n\n## Heading 1\ntext\n## Heading 2\nmore text")

        // extract just the proposed TOC ("dry-run")
        toc, _ := mdtoc.New(b)
        fmt.Println(toc.String())

        // OR insert TOC into an existing document
        out, _ := mdtoc.Insert(b, mdtoc.DefaultConfig)
        fmt.Println(string(out))
}

Documentation

Overview

Package mdtoc generates a table of contents for an existing markdown document

Index

• Variables
• func Insert(b []byte, cfg *Config) ([]byte, error)
• type Config
• type Item
• type Toc
  • func New(b []byte) (*Toc, error)
  • func (t *Toc) Bytes() []byte
  • func (t *Toc) String() string

Variables

var (
	// ErrExistingToc is thrown if the provided document already contains a mdtoc-generated
	// table of contents
	ErrExistingToc = errors.New("document has existing table of contents")

	// Version is the current library/CLI version
	//go:embed VERSION
	Version string

	// DefaultConfig defines the default configuration settings
	//
	// These field values will align with the default flag values from the CLI
	DefaultConfig = &Config{
		Force:          false,
		WithTocHeading: false,
		TocHeading:     DefaultTocHeading,
	}

	// DefaultTocHeading is the default heading applied when enabled
	DefaultTocHeading = "Table of Contents"
)

Functions

func Insert

func Insert(b []byte, cfg *Config) ([]byte, error)

Insert returns a copy of an existing document with a table of contents inserted

Types

type Config

type Config struct {
	Force          bool
	WithTocHeading bool
	TocHeading     string
}

Config stores settings to be used when inserting a new Toc

type Item

type Item struct {
	Indent int
	Text   string
	Link   string
}

Item represents a single line in the table of contents

type Toc

type Toc struct {
	Items  []Item
	Config *Config
}

Toc stores table of contents metadata

func New

func New(b []byte) (*Toc, error)

New extacts table of contents attributes from an existing document

func (*Toc) Bytes

func (t *Toc) Bytes() []byte

Bytes returns a markdown formatted slice of bytes

func (*Toc) String

func (t *Toc) String() string

String returns a markdown formatted string