Generating TOCs

The doctoc tool generates table of contents sections for markdown files.

Installing Node.js, npm and `doctoc``

doctoc is distributed with the Node Package Manager. Node is a JavaScript runtime environment.

On Ubuntu, Node can be installed with:

sudo apt update
sudo apt install nodejs

On Windows, with Chocolatey:

choco install nodejs

Installers and binaries for Windows and macOS are available for download.

Once Node is installed, install doctoc with:

npm install -g doctoc

Using doctoc

Then TOCs can be generated with doctoc <file>, e.g.:

doctoc DEVELOPER.md

This will insert HTML comments surrounding an automatically edited region, in which doctoc will create an appropriately indented TOC tree. Subsequent runs are idempotent, scanning for headers and only updating the TOC if the file header structure has changed.

To run doctoc for all markdown files in a particular directory (recursive), use doctoc some/path.

By default doctoc inserts a self-descriptive comment

Table of Contents generated with DocToc

This can be removed (and other content within the TOC region edited) — doctoc will not overwrite it, only the table.