How to use the markdown table of contents generator
- Paste your Markdown. Headings that start with # (up to six) or are underlined with === or --- are found. Code blocks are skipped.
- Choose the highest and lowest level to list, such as level 2 to level 3.
- Choose the list style (dashes, stars or numbers), the indent and whether each entry links to its heading.
- Copy the table of contents and paste it where you want it, usually near the top of the file.
A short project guide
For a guide with the headings Getting started (with Install and Configure inside it), Usage (with Command line and Library), a second Usage and License, levels 2 to 3 give a nested list. The first Usage links to #usage and the second to #usage-1, because repeated headings get a counter, as GitHub does.
Anchors follow the GitHub rule: lower case, characters other than letters, numbers, hyphens, underscores and spaces removed, and spaces turned into hyphens. "What's new? C++ & C#" becomes #whats-new-c--c, and "Über uns" becomes #über-uns. Formatting such as bold, code ticks and links is stripped from the heading text first.
How the list is built
Each heading in the chosen level range becomes one line. A heading is nested under the one before it if it has a deeper level, so a level 4 right after a level 2 appears one step in, not two, which keeps the list tidy. Numbered lists restart at each new group.
Setext headings, written as a line of text underlined with equal signs or hyphens, count as level 1 and level 2. A line of hyphens under a paragraph can also be read as an underline, so check the result if your document uses horizontal rules.
Anchors depend on the site
GitHub, GitLab and other sites build anchors a little differently, particularly for punctuation and non-English letters. The links here follow GitHub, which many other tools copy. If you publish somewhere else, open the page and click a link to confirm it works. To write and preview Markdown, use the Markdown Editor and Previewer. Make tables with the Markdown Table Generator, draft a README with the README Generator, and strip formatting with the HTML to Text Converter.
Assumptions and limits
- Headings inside fenced code blocks (three backticks or three tildes) are ignored. Indented code blocks and HTML headings are not read.
- Up to 2,000,000 characters are accepted. Everything runs in your browser.
- Anchors follow the GitHub rule, with -1, -2 added to repeated headings.
- The title of the table of contents itself is not added. Write your own heading above the list.
Frequently asked questions
Why does the table skip my heading?
It may be outside the level range you chose, inside a code block, or missing the space after the # signs. A heading needs a space after the hashes, so #tag is text, not a heading.
How are repeated headings linked?
The first keeps its plain anchor and later ones get -1, -2 and so on in the order they appear. This matches how GitHub numbers them, so the links point at the right place.
Can I list every level?
Yes. Set the highest level to 1 and the lowest to 6. A long list with every level can be harder to use than one limited to two or three levels.
Will the links work on every site?
They follow GitHub's rule, which many sites copy. Others build anchors differently, so open the published page and click a link to check.