Guide
Generating a table of contents for Markdown
A long README or documentation page is much easier to use with a table of contents at the top: readers see the structure and jump to the part they need. Writing one by hand is tedious, and the links break whenever a heading changes or the anchor rules are misunderstood. This generator reads your headings, builds the list with anchors that match GitHub or GitLab, and can insert it into the file for you.
How anchors are made
When GitHub renders Markdown, it gives every heading an anchor: the text in lower case, punctuation removed, each space turned into a hyphen. Underscores and hyphens are kept, and letters in other alphabets are kept too. A heading that appears twice gets -1 on the second occurrence, -2 on the third. GitLab follows nearly the same rules but merges runs of hyphens into one. Choose the platform and the links match.
Which headings count
Both heading styles are read: lines starting with # signs, and “setext” headings underlined with === or —. Anything inside a fenced code block is ignored, so an example heading in a code sample does not appear in the TOC. If a heading ends with an explicit id such as {#install}, that id is used as the anchor, as many site generators allow.
Levels and list style
By default the TOC covers levels 2 and 3 — the sections and subsections under the title. Widen or narrow the range as needed. Choose hyphen or asterisk bullets or a numbered list, and two- or four-space indentation; some linters and renderers insist on four spaces for nested lists, especially under numbered items. Turn links off for a plain outline.
Inserting and updating
“Whole file” returns your Markdown with the TOC placed between <!-- toc --> and <!-- tocstop --> comments. The first time, it goes straight after the H1 title. After you edit headings, paste the file in again: the list between the markers is replaced rather than duplicated. These are the same markers used by common TOC tools, so other tools can maintain the block too.
Checking anchors
The table under the output lists every heading with its level and anchor. Use it to check a link written by hand elsewhere in your documentation, or to spot duplicates that will get numbered suffixes.
A worked example
In the sample README, “Colours & themes” becomes #colours–themes, “What’s new in v2.0?” becomes #whats-new-in-v20, and the second “Getting started” becomes #getting-started-1. The heading inside the code block is left out.
Tips for a useful TOC
Keep headings short and distinct, since they become the TOC entries; avoid two sections with the same name at the same level; and limit the TOC to two levels on long pages so it stays a summary.
Linking to headings from elsewhere
The same anchors work in links from other pages: README.md#install on GitHub, or docs/setup.md#configuration in a documentation site. Before renaming a heading that other pages link to, search for its anchor; the old links break silently, landing at the top of the page instead of the section.
Related tools
Convert the file to a web page with Markdown to HTML, write and preview it in the Markdown Editor, add collapsible FAQ sections with the HTML Accordion Generator, or make URL-safe names with the Slug Generator.
Checked against the current version of the Markdown Table of Contents Generator on .