https://github.com/jar-b/mdtoc
Generate a table of contents for an existing markdown document.
https://github.com/jar-b/mdtoc
cli markdown table-of-contents table-of-contents-generator
Last synced: 3 months ago
JSON representation
Generate a table of contents for an existing markdown document.
- Host: GitHub
- URL: https://github.com/jar-b/mdtoc
- Owner: jar-b
- License: mit
- Created: 2021-05-14T04:28:32.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2023-09-15T20:25:42.000Z (almost 2 years ago)
- Last Synced: 2025-02-13T14:52:50.451Z (5 months ago)
- Topics: cli, markdown, table-of-contents, table-of-contents-generator
- Language: Go
- Homepage: https://pkg.go.dev/github.com/jar-b/mdtoc
- Size: 45.9 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mdtoc
[](https://github.com/jar-b/mdtoc/actions/workflows/build.yml)
[](https://goreportcard.com/report/github.com/jar-b/mdtoc)
[](https://pkg.go.dev/github.com/jar-b/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](#cli)
* [Installation](#installation)
* [Usage](#usage)
* [Examples](#examples)
* [Library](#library)
* [Usage](#usage-1)
## CLI
### Installation
Via `go install`:
```sh
go install github.com/jar-b/mdtoc/cmd/mdtoc@latest
```
### Usage
```
$ mdtoc -h
Generate a table of contents for an existing markdown document.
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
```sh
# 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
```go
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))
}
```