How to add a table of contents in Markdown

Markdown has no contents directive: a table of contents is a list of links to heading anchors, like - [Install](#install). Each anchor is the heading text in lowercase, with spaces turned into hyphens and punctuation removed.

Markdown has no table-of-contents directive. A contents list is a list of ordinary links pointing at heading anchors:

- [Installing](#installing)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

Every heading gets an anchor automatically. Nothing has to be declared.

How the anchor is generated

Take the heading text, then:

1. lowercase it
2. replace each space with a hyphen
3. remove punctuation
4. leave everything else alone

When two headings share the same text, the first keeps the plain anchor, the second gets -1, the third -2, in document order. These are the rules GitHub documents for section links, and this editor follows them, so a contents list that works in the preview works on GitHub.

This is where most broken anchor links come from: the brackets, the colon or the emoji in the heading is gone from the slug, and the guess does not match. Render the page and copy the link from the heading rather than working it out by hand.

Custom anchors

## Configuration {#config}

Works in kramdown (Jekyll), Pandoc, Python-Markdown and Quarto. GitHub renders the braces as literal text.

Where HTML is allowed, this works anywhere, GitHub included:

<a name="config"></a>
## Configuration

Empty anchor immediately before the heading. Ugly, portable, and the form GitHub’s own documentation gives for custom anchors.

What builds the list for you

GitHub shows a contents dropdown at the top-right of any rendered Markdown file. There is nothing to add to the file: it is built from the headings.

Static site generators (Hugo, Jekyll, Docusaurus, MkDocs) all have a built-in contents variable you place in the template rather than the document.

The editor on this page builds one live in the Contents panel while you type, and clicking an entry scrolls the preview to it. That is a reading aid rather than something inserted into the file, so the file stays clean.

If you want the list in the file (a README, where the reader may be looking at raw text) write it by hand and keep it short. A contents list longer than the screen is worse than none.

Linking between files

The same hash works after a path:

[the config section](docs/setup.md#configuration)

On GitHub this resolves relative to the current file. In a static site it resolves against the built URL, which may not be the same path: check one before writing fifty.