mdtoc

View Github Pages

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

generate, strip, regen/refresh, check without turning your Markdown into a moving target.

Table of Contents

(click to expand)

• 1. Features
• 2. Install
  • 2.1. Releases
  • 2.2. Build from source
• 3. Usage
  • 3.1. Inspect the CLI
  • 3.2. Use EXAMPLE.md as play ground
• 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 vsCode extension
• configurable: CLI or edit generated <!-- 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
• works with files and Unix pipes
• repeated headings support
• ignores headings:
  • in Setext stype
  • inside fenced code blocks
  • inside HTML comments: <!-- ... ## Example -->
  • between exclusion regions: <!-- mdtoc off --> … <!-- mdtoc on -->
• generated content stays clearly separated from authored content
• deterministic and idempotent output

2. Install

2.1. Releases

Download a prebuilt binary from GitHub Releases.

Homebrew tap install:

brew install rokath/tap/mdtoc

2.2. 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 EXAMPLE.md as play ground

mdtoc EXAMPLE.md                                   # root mode: regen if managed, otherwise generate
cat EXAMPLE.md | mdtoc -n off -a off               # root mode on stdin: generate a dry-run ToC-only view
mdtoc EXAMPLE.md -a off --toc off                  # root mode: explicit generate because flags override regen
mdtoc generate EXAMPLE.md --slug gitlab            # explicit command with positional file input
cat EXAMPLE.md | mdtoc strip > EXAMPLE.stripped.md # remove managed artifacts via Unix pipe and write to a different file
mdtoc regen EXAMPLE.md                             # rebuild generated output from the stored container config
mdtoc refresh EXAMPLE.md                           # alias for regen
mdtoc generate EXAMPLE.md                          # generate with current CLI flags or defaults and rewrite the config block
mdtoc check EXAMPLE.md                             # fail in CI when EXAMPLE.md differs from the reconstructed target state

• gitlab follows GitLab heading IDs; punctuation-heavy titles can therefore differ from github (for example 3.5 -> 35). See GitLab slug profile.
• Exactly one input source is allowed per invocation: positional file, --file/-f, or piped stdin.
• 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 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. regen reuses the stored container config, or defaults if the config block was deleted. refresh is a command alias for regen.

This means:

• the stored config is persisted generator input
• regen rebuilds generated output from that config
• refresh is an alias for regen
• check validates against regenerated output
• changing generation settings must go through generate, not through manual config edits

5. Limits

• repeated-heading links depend on occurrence order (issue #8)
  • Workaround: example
• The per default with anchor=true generated ToC links guaranty to work in any environment, but reduce the readability of the raw Markdown document. With anchor=off numbering=off slug=crossnote a good working setting is possible. But switching numbering=on breaks the link stability promise then. There is no generally best setting - you have to choose.
• not a site generator
• not a Markdown formatter

6. Documentation

6.1. Specification

• mdtoc spec

6.2. Comparison

• mdtoc alternatives
• mdtoc VS Code extension MVP

7. Status

+ READY TO USE +