# 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.

Stars: 4.5k · Language: JavaScript · License: MIT · Categories: Dev Tools

- Repository: https://github.com/thlorenz/doctoc
- Website: https://www.npmjs.com/package/doctoc
- Page: https://www.trmn.sh/tools/doctoc

## Install

- npm: `npm install -g doctoc`

## Overview

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

```bash
# via npm
npm install -g doctoc
```

## Alternatives

- [mermaid-cli](https://www.trmn.sh/tools/mermaid-cli.md): Command-line tool (mmdc) that renders Mermaid diagram definitions and Markdown files with Mermaid code blocks to SVG, PNG, or PDF. (JavaScript, 5.2k stars)
- [Plop](https://www.trmn.sh/tools/plop.md): Micro-generator framework that runs inquirer prompts and Handlebars templates from a plopfile to create consistent files from the terminal. (JavaScript, 7.7k stars)
- [np](https://www.trmn.sh/tools/np.md): Interactive release tool for npm packages that checks the working tree, runs tests, bumps versions, creates tags, publishes, and pushes to Git. (JavaScript, 7.7k stars)
- [release-it](https://www.trmn.sh/tools/release-it.md): Generic CLI for automating releases: version bumps, git commit/tag/push, changelogs, GitHub/GitLab releases, and npm publishing, with hooks and plugins. (JavaScript, 9.1k stars)
- [terminalizer](https://www.trmn.sh/tools/terminalizer.md): Terminal session recorder that generates animated GIF images from command-line sessions (JavaScript, 16.2k stars)

---

Canonical: https://www.trmn.sh/tools/doctoc
