Markdown Table of Contents Generator

mdtoc is a utility for generating a table-of-contents for markdown files.

Only github-flavored markdown is currently supported, but I am open to accepting patches to add other formats.

Table of Contents

Generated with mdtoc --inplace README.md

• Usage
• Installation
• Community, discussion, contribution, and support
  • Code of conduct

Usage

Usage: mdtoc [OPTIONS] [FILE]... Generate a table of contents for a markdown file (github flavor).

TOC may be wrapped in a pair of tags to allow in-place updates:

<!-- toc -->
generated TOC goes here
<!-- /toc -->

TOC indentation is normalized, so the shallowest header has indentation 0.

Options:

--dryrun / -d - Whether to check for changes to TOC, rather than overwriting. Requires --inplace flag. Exit code 1 if there are changes.

--inplace / -i - Whether to edit the file in-place, or output to STDOUT. Requires toc tags to be present.

--skip-prefix / -s - Whether to ignore any headers before the opening toc tag. (default true)

--max-depth / -m - Limit the depth of headers that will be included in the TOC. (default 6)

--output / -o - Write the TOC to the specified file instead of STDOUT.

--version / -v - Show MDTOC version.

Stdin support:

Use - as the file argument to read markdown from stdin:

cat README.md | mdtoc -

Glob patterns:

File arguments are expanded as glob patterns, which is useful on systems that do not perform shell expansion (e.g., Windows):

mdtoc -i "docs/*.md"

For example, with --skip-prefix=false the TOC for this file becomes:

- [Markdown Table of Contents Generator](#markdown-table-of-contents-generator)
- [Table of Contents](#table-of-contents)
  - [Usage](#usage)
  - [Installation](#installation)

Installation

On linux, simply download and run the standalone release binary

# Optional: Verify the file integrity - check the release notes for the expected value.
$ sha256sum $BINARY
$ chmod +x $BINARY

Or, if you have a go development environment set up:

go install sigs.k8s.io/mdtoc@latest

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page.

You can reach the maintainers of this project at:

• Slack
• Mailing List

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.