Markdown Table of Contents: Why Your Links 404

Contents

• Does Markdown Have a TOC Syntax?
• How GitHub Turns Headings Into Anchors
• Six Slug Rules That Break Hand-Written TOCs
• GitHub's Built-In Table of Contents Menu

Does Markdown Have a TOC Syntax?

No. There is no [TOC], no [[TOC]], and no directive in the markdown spec. Those markers exist, but each belongs to a specific renderer, not to markdown itself.

How GitHub Turns Headings Into Anchors

GitHub builds an id for every markdown heading, and a TOC link works only when your #fragment matches that generated id exactly.

Six Slug Rules That Break Hand-Written TOCs

I ran these headings through github-slugger 2.0.0 to get the exact output rather than guess at it. The results are unintuitive enough to be worth memorising.

GitHub's Built-In Table of Contents Menu

Before you hand-write anything, check whether you need to. On 13 April 2021 GitHub shipped automatic table of contents support: "Markdown files will now automatically…

Where the TOC Markers Actually Work

If you've seen [TOC] work somewhere, you weren't imagining it — you were on a different renderer.

How to Generate a Markdown Table of Contents Automatically

For a README that needs an inline, curated markdown TOC, generating the list beats typing it.

Linking Your Profile README's Sections

Profile READMEs are where this bites hardest, because they're short enough that a four-item TOC is genuinely useful and visible enough that a dead link looks careless.

Want the details?

The six slug rules, GitHub's built-in TOC menu, and what works for READMEs and profile pages.