DocToc
Node.js CLI that generates and updates tables of contents in Markdown files, with anchor links compatible with GitHub, GitLab, Bitbucket, Ghost and nodejs.org.
DocToc is a command-line tool that inserts and updates tables of contents in Markdown files. You pass it one or more files or directories (for example doctoc .). For directories it searches recursively and processes files with the .md, .markdown and .mdx extensions, skipping .git and node_modules by default. The generated TOC is placed between pragma comments, so re-running the command updates the existing block instead of duplicating it.
Anchor links default to GitHub-style, and a mode flag switches the format for other sites: --bitbucket, --nodejs, --github, --gitlab or --ghost. The TOC can be customised with options such as --minlevel and --maxlevel for heading depth, --toc-location (top or before), --title and --notitle, --toc-header-content and --toc-footer-content, --mintocitems, and --document-lines-min. List output can be unordered or ordered (--toc-list-format), with number, roman, or letter styles (--toc-list-style). Bullet symbols (--entryprefix) and indentation style and width are also configurable. A compact pragma style is available in place of the default legacy comments.
For automation, --dryrun makes no changes and exits with code 1 if any file's TOC is out of date, which suits CI checks. Exit code 2 indicates invalid config options. --update-only (-u) leaves files that have no TOC untouched, which the README suggests for use with lint-staged. -s or --stdout prints the result for a single file, and --loglevel sets verbosity. The README also has sections on using doctoc as a git hook and as a Docker image.
It is aimed at developers and documentation maintainers who keep READMEs and docs in git repositories and want TOCs regenerated by a command, a hook, or a CI step.
Installation
# via npm
npm install -g doctoc
Alternatives & related tools
mermaid-cli
Command-line tool (mmdc) that renders Mermaid diagram definitions and Markdown files with Mermaid code blocks to SVG, PNG, or PDF.
Plop
Micro-generator framework that runs inquirer prompts and Handlebars templates from a plopfile to create consistent files from the terminal.
np
Interactive release tool for npm packages that checks the working tree, runs tests, bumps versions, creates tags, publishes, and pushes to Git.
release-it
Generic CLI for automating releases: version bumps, git commit/tag/push, changelogs, GitHub/GitLab releases, and npm publishing, with hooks and plugins.
terminalizer
Terminal session recorder that generates animated GIF images from command-line sessions
add a badge to your README
Maintain DocToc? Show that it's featured on trmn. The badge links back to this page.
[](https://www.trmn.sh/tools/doctoc?utm_source=badge)<a href="https://www.trmn.sh/tools/doctoc?utm_source=badge"><img src="https://www.trmn.sh/badge/doctoc.svg" alt="Featured on trmn" height="20"></a>