How anchors are made
| Heading | Anchor |
|---|---|
## Install | #install |
## Getting help | #getting-help |
## Step 2: Deploy | #step-2-deploy |
## What's new? | #whats-new |
Lower case, spaces become hyphens, punctuation is dropped. A heading that
appears twice gets -1 added to the second one.
Nest it to match the headings
Indent ### headings under their ## heading, the same as a nested list.
Keep the contents to two levels; deeper gets hard to scan.
[TOC] is not standard
Some apps replace [TOC] with a generated contents list. It is not part of
Markdown, and GitHub, MarkdownPaper and most other apps show it as the text
[TOC].
Apps that build one for you
You may not need to write one at all:
- GitHub adds an outline menu to README files with headings.
- MarkdownPaper shows the contents in the page margin of any document with three or more headings, and marks the section you are reading.
- Editors like VS Code can generate the list with an extension, and keep it up to date as you edit.
A written contents list is still worth having in a document that will be printed, or read somewhere that does not build one.
Keep it up to date
A table of contents written by hand goes out of date the moment a heading is renamed, and the link breaks. Check the links after renaming a heading, or let an app or an editor build the list.
Questions
Can Markdown generate a table of contents automatically?
Not by itself. Some apps and editors generate one, and some readers show one beside the document, but plain Markdown needs a list of links.
Why does my table of contents link not work?
The anchor does not match the heading. Check that it is lower case, with hyphens for spaces and no punctuation.
Should a README have a table of contents?
Only a long one. For a short README the headings are enough, and GitHub adds an outline menu anyway.
Next
- Markdown headings, and how to give one your own anchor.
- Read a long document with its contents in the margin.