mdtoc

View Github Pages

mdtoc: Markdown Table of Contents ☰ with numbering and stable anchor links

generate, strip and check without turning your Markdown into a moving target.

Table of Contents (click to expand)

• 1. Features
• 2. Install
  • 2.1. VS Code extension
  • 2.2. Release Binaries (Linux, MacOS, Windows)
  • 2.3. Darwin Setup
  • 2.4. Build from source
• 3. Usage
  • 3.1. Inspect the CLI
  • 3.2. Use .docs/EXAMPLE.md as a playground
• 4. Managed Structure
• 5. Limits
• 6. Documentation
  • 6.1. Specification
  • 6.2. Comparison
• 7. Status

1. Features

• easy to use: mdtoc MY.md, single binary, also as VS Code extension

  • same binary in scripts, CI and as VS Code extension keeps workflow aligned

• configurable: CLI or edit generated config:

  <!-- numbering=true min=2 max=4 slug=github anchor=true link=true toc=true bullets=auto -->

  • on|off for numbering, anchor, link, toc
  • targets ATX headings (min # to max ######)
  • slug profiles: github, gitlab, crossnote
  • auto or explicit (*, -, +) ToC bullets style

• move the generated ToC with its container to any place - it will be re-generated there

• protects non-generated content inside ToC area

  • generated content stays clearly separated from authored content

• works with files and Unix pipes

• repeated headings support

• Intentionally ignored:

  • Setext: IGNORED Title underlined with === or ---
  • fenced code blocks: ```txt ## IGNORED Title ```
  • HTML comments: <!-- ## IGNORED Title -->
  • exclusion regions: <!-- mdtoc off --> ## IGNORED Title <!-- mdtoc on -->
  • starting space: ␠## IGNORED Title

• deterministic and idempotent: updates existing ToC

2. Install

2.1. VS Code Extension

CLI install: code --install-extension rokath.mdtoc or open VS Code, click Extensions, enter mdtoc:

2.2. Release Binaries (Linux, MacOS, Windows)

Download a prebuilt binary from GitHub Releases.

2.3. Darwin Setup

Homebrew tap install:

brew install rokath/tap/mdtoc

2.4. Build from source

go build ./cmd/mdtoc

3. Usage

3.1. Inspect the CLI

mdtoc --help        # show compact CLI usage and commands
mdtoc --verbose     # show extended root help with command details
mdtoc <command> -v  # show the long help for one command

3.2. Use .docs/EXAMPLE.md as a playground

mdtoc EXAMPLE.md                    # root mode: update an existing managed container or create a new one
mdtoc generate EXAMPLE.md -a false  # new ToC, use CLI or defaults, rewrite the config block
mdtoc check EXAMPLE.md              # fail in CI when ToC differs from the reconstructed ToC
cat EXAMPLE.md | mdtoc              # dry-run
cat EXAMPLE.md | mdtoc strip > s.md # clear via Unix pipe and write to a different file

• Exactly one input source is allowed: piped stdin or file i/o (with or without --file/-f).
• Small CLI note: the Go-style one-dash long form such as -toc off is currently tolerated, but --toc off remains the documented form.

4. Managed Structure

mdtoc uses an explicit container so generated content is easy to spot and safe to regenerate.

(click to expand)

<!-- mdtoc -->

* [About](#about)

<!-- numbering=true min=2 max=4 slug=github anchor=true link=true toc=true bullets=auto -->
<!-- /mdtoc -->

The heading title stays the source of truth. Numbers, inline anchors, and ToC entries are derived from it. With anchor=false, the ToC target follows the rendered heading text because no managed inline anchor exists. Use slug=github|gitlab|crossnote to control the renderer/profile-dependent link type generation.

The optional config block records the settings used for regeneration. generate uses current CLI flags or defaults and then rewrites that block when settings need to be persisted.

This means:

• the stored config is persisted generator input
• check validates against regenerated output
• changing generation can go through generate, or manual config edits

5. Limits

• repeated-heading links depend on occurrence order (#8)
  • Workaround: example
• The check command does not detect duplicate link anchors. See #97.
• By default, anchor=true generates ToC links that reliably work in any environment, but this reduces the readability of the raw Markdown document. A setting like anchor=false numbering=false slug=crossnote can work well in some renderers. Switching numbering=on there breaks the link stability promise, though. There is no universally best setting; you have to choose. See also #94.
• not a site generator
• not a Markdown formatter

6. Documentation

6.1. Specification

• mdtoc spec
• mdtoc VS Code extension
• EXAMPLE.md

6.2. Comparison

• mdtoc alternatives

7. Status

+ READY TO USE +