DocToc rewrites the table of contents block between its own pragmas
📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.
At a glance
- What is it?
- thlorenz/doctoc is a command line tool that inserts and refreshes tables of contents in markdown files. It parses headings with a markdown to AST library, renders anchors for a named set of hosts, and confines its edits to the block between two HTML comment pragmas.
- Who is it for?
- DocToc suits a repository where markdown docs are checked in and headings move around, especially with a lint-staged or CI check attached. Before adopting it, confirm the ignore and hook flags you need are documented for your setup, decide whether HTML headings at depth five and below matter to you, and read the generated block rather than hand editing it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- thlorenz/doctoc4,475 ★ · +11
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| thlorenz/doctoc | 4.5k | 4.5k |
11 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The published tool is one bin entry plus a lib directory
Installation is a single global command, and the first useful run points it at a file or a directory.
npm install -g doctoc
doctoc README.md --bitbucketThe manifest declares the same file twice, as `main` and as `bin`, both pointing at `doctoc.js`, and the published `files` array contains only `lib`. So the executable lives at the repository root and the code it loads ships from `lib/`. Arguments are parsed by minimist, log lines go through loglevel, heading text becomes anchors through anchor-markdown-header, and the file itself is turned into an AST by @textlint/markdown-to-ast before htmlparser2 touches any embedded HTML.
Tests run on tap, which is also the `test` script and has its own config file `.taprc` in the root next to the `test/` directory. The version field reads `0.0.0-development`, so the manifest carries no published version of its own. The maintainers dogfood the flags in their npm scripts, running the tool against their own README:
"scripts": {
"test": "tap",
"doctoc": "node doctoc.js README.md --update-only --maxlevel 4 --loglevel trace",
"doctoc:dry-run": "node doctoc.js README.md --update-only --maxlevel 4 --loglevel trace --dryrun"
},The pragma pair is the boundary of every rewrite
DocToc does not scatter markers through a document. It looks for an opening and a closing comment that mark one region, and replaces only what sits between them. The default pragma style is called `legacy` and looks like this:
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
{{toc}}
<!-- END doctoc generated TOC please keep comment here to allow auto update -->The inner line is a placeholder for the generated list. The second comment is aimed at humans and pull request reviewers who see the diff. A second style, `compact`, keeps the same idea in three lines:
<!-- START doctoc -->
{{toc}}
<!-- END doctoc -->Because the region is delimited rather than inferred from headings, you can also place extra text in the header. The `--toc-header-content` option writes a line below the pragma, so `doctoc --toc-header-content 'My Header' .` puts your own string between the opening comment and the list. The practical consequence is that a table of contents can be moved by hand: cut the block, pragmas included, and paste it where you want it, then the next run rewrites it in place.
--dryrun leaves files alone and exits 1 when they are stale
The integration path most projects want first is a check, not an edit. The `--dryrun` option suppresses every write and instead returns exit code 1 to signal that files are out of date and should be updated. In a CI job that turns a stale table of contents into a failed build step rather than a surprise commit. The companion `doctoc:dry-run` script in the manifest shows the same idea pointed at a single file with `--update-only --maxlevel 4 --loglevel trace`.
`--update-only`, short form `-u`, restricts the run to files that already carry a table of contents and leaves markdown files without one untouched, which is what makes it safe to point at a whole directory from a pre-commit setup such as lint-staged. The `.pre-commit-hooks.yaml` file in the repository root is where such an integration would be declared.
Printing instead of writing has its own constraint: the `-s` or `--stdout` option only applies when you name a single file. For a folder or several files, `--dryrun` is the option the documentation points you at. Verbosity runs from trace to error, with info as the default, so `--loglevel warn .` is the way to quiet a large repository scan.
A directory run only collects .md, .markdown and .mdx
The CLI accepts both a file path and a directory path, and the directory case is the one with rules. The search recurses, and only three extensions are processed: `.md`, `.markdown` and `.mdx`. Anything else in the tree is skipped.
Two directories are skipped by default during that recursion: `.git` and `node_modules`, if they exist. That default saves the common case, where a checkout has both, and it means vendor trees do not get rewritten.
The documentation's own table of contents also names a section for ignoring individual files; read it for the exact mechanism before relying on per-file exclusions.
Anchor compatibility is a mode flag with five named hosts
A table of contents is only useful if its links land on real anchors, and anchor slugs differ between hosts. DocToc handles that with one mode flag rather than by guessing. The named modes are:
--bitbucket bitbucket.org
--nodejs nodejs.org
--github github.com
--gitlab gitlab.com
--ghost ghost.orgPassing one of them switches the anchor generation for that host, and the flag takes no value:
doctoc README.md --bitbucketFive sites are listed, and nothing in the option set names a sixth. That is the practical limit to plan around: if your markdown is rendered by an internal wiki, a docs product or a static site generator with its own slug rules, there is no mode for it in this list, and the generated links will follow the default behavior instead of that host's. Check one generated anchor by hand against the rendered page before committing a whole tree of them.
--minlevel only accepts 1 and 2, and HTML headings stop at four
Heading selection has three controls. `--minlevel` limits entries to headings at or above a level, and the documentation is blunt about the range: currently supported values are only 1 and 2, with 1 as the default. `--maxlevel` limits entries from the top down, and its default is asymmetric, since no limit is placed on markdown formatted headings while headings from embedded HTML are limited to four levels.
That asymmetry is the detail worth remembering. Markdown headings can nest as deep as the document goes, but by default an `<h5>` or deeper written as raw HTML does not appear in the table of contents.
The third control is placement rather than depth. `--all` includes every heading regardless of where it sits in the document, whereas the default behavior keeps only headings below the table of contents itself. In a document where the table of contents starts at the top, that default conveniently skips the headings above it, but in a file where you move the block into the middle, headings before it vanish from the list until you add `--all`.
--toc-location defaults to top and is scheduled to move before
Where the block lands is a separate decision from what goes in it. The `--toc-location` option takes `top` or `before`. `top` inserts the table of contents at the top of the document, before any markdown content but after any frontmatter if it is defined. `before` inserts it immediately before the first heading that appears in the table of contents.
The default is `top` today, and the documentation says that in v3 it will change to `before`. That is a scheduled behavior change for anyone pinning the version, and it means the same command produces a different file layout on the next major release.
The two modes interact with `--minlevel` rather than working alone. To insert the list before the first level 2 heading, the documented form is:
doctoc --toc-location before --minlevel 2 .The minimum lines threshold is the other gate on insertion. `--document-lines-min` sets how long a document must be before it gets a table of contents at all, with 0 as the default, so `doctoc --document-lines-min 200 .` skips every file under that length. The count is textual rather than structural: images are counted the same as plain words, and repeated newlines count too.
Undocumented corners: the heading list, per-file ignores and Docker
The README's own table of contents also lists sections on excluding a heading, ignoring individual files, exit codes, the list, the table of contents items and the footer, usage as a git hook, and a Docker image. The repository root carries `.pre-commit-hooks.yaml`, `AGENTS.md`, `tea.yaml` and a `.github/` directory.
Anyone who wants to drop a heading from the list, keep a generated API reference out of a scan, or install the tool from a container image should read those README sections for the exact switch names. Anyone who runs DocToc from a git hook should assume they are on the `top` default and that the v3 change to `before` will move their block, unless they pin the option explicitly.
Editorial conclusion
DocToc suits a repository where markdown docs are checked in and headings move around, especially with a lint-staged or CI check attached. Before adopting it, confirm the ignore and hook flags you need are documented for your setup, decide whether HTML headings at depth five and below matter to you, and read the generated block rather than hand editing it.
Frequently asked questions
How do I install DocToc and generate a table of contents?
Run `npm install -g doctoc`, then point the command at a file or a directory. A directory run recurses and processes only `.md`, `.markdown` and `.mdx` files, skipping `.git` and `node_modules` by default.
How can DocToc check documentation in CI without rewriting files?
Use the `--dryrun` option, which writes nothing and returns exit code 1 when files are out of date. The `-s` or `--stdout` option only applies to a single filename, so folders and multiple files use the dry run instead.
Does DocToc generate anchors for GitLab and Bitbucket?
Yes, through mode flags: `--bitbucket bitbucket.org`, `--nodejs nodejs.org`, `--github github.com`, `--gitlab gitlab.com` and `--ghost ghost.org`. Each flag takes no value, as in `doctoc README.md --bitbucket`.
What does the --update-only flag change in DocToc?
It updates only the table of contents that already exists and leaves markdown files without one untouched, which suits pairing the tool with lint-staged. The short form is `-u`.
How many heading levels can a DocToc table of contents contain?
The `--minlevel` option defaults to 1 and currently supports only the values 1 and 2. For the upper end, `--maxlevel` places no limit on markdown formatted headings, while headings from embedded HTML are limited to four levels.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/thlorenz-doctoc)Star history chart for your README
[](https://hysenlabs.com/projects/thlorenz-doctoc)Was this useful?