How to Create a Table of Contents in Markdown (With Anchor Links)

Long Markdown documents become hard to navigate fast. Readers scroll endlessly looking for the section they need. A table of contents fixes this by giving them a clickable map at the top of the page. The good news is that Markdown can build one using nothing more than links and headings.

Quick Answer: To create a table of contents in Markdown, add a bulleted list of links where each link points to a heading’s anchor. The anchor is the heading text in lowercase with spaces replaced by hyphens, written as [Section Title](#section-title). Many platforms also generate the table automatically from your headings.

This guide shows the manual method that works everywhere, the automatic options on common platforms, and how to avoid the anchor mistakes that break links.

How Do Anchor Links Work in Markdown?

Every heading in a rendered Markdown document quietly gets an id. That id is derived from the heading text. When you link to #that-id, the browser jumps to the heading. This is the foundation of any Markdown table of contents.

The standard rule for turning a heading into an anchor is:

• Convert all letters to lowercase
• Replace each space with a hyphen
• Remove punctuation such as periods, commas, and parentheses

So a heading like ## Installation and Setup becomes the anchor #installation-and-setup. Get this transformation right and your links work. Get it slightly wrong and they silently fail.

How Do You Build a Table of Contents Manually?

The manual method works in every Markdown renderer because it uses only standard links. Suppose your document has these headings:

## Getting Started
## Configuration
## Troubleshooting

You write the table of contents as a list of anchor links:

## Contents

- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

Each link jumps to its section when clicked. For nested structure, indent sub items to mirror your H3 headings:

- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [Advanced Options](#advanced-options)

You can preview the result live in edtr.md and click each link to confirm it lands on the right heading before you publish.

Can a Table of Contents Be Generated Automatically?

Yes, and on several platforms you do not have to write it by hand at all.

• GitHub shows an automatic, collapsible table of contents in the header of any rendered Markdown file, built from your headings.
• Static site generators like many documentation frameworks insert a table of contents from a simple marker or a configuration flag.
• Editor extensions can scan your headings and write the link list for you, then update it as you edit.

Automatic generation is convenient, but the manual method is the most portable. If you need a document that behaves the same everywhere, hand written anchor links are the safe choice.

Why Do My Anchor Links Break?

A few recurring issues account for most broken table of contents links:

• Duplicate headings. Two headings with identical text get different ids, usually with a -1 suffix on the second one. Link to #setup and #setup-1 accordingly.
• Punctuation. Anchors strip most punctuation, so ## What's New? becomes #whats-new, not #what's-new?.
• Emoji and special characters. These are often removed entirely, which changes the anchor.
• Platform differences. GitHub, GitLab, and various renderers follow slightly different anchor rules, so a link that works in one may need adjusting in another.

When a link fails, the fastest fix is to render the document and inspect the actual id the renderer assigned, then match your link to it.

What Are Some Best Practices?

A few habits keep your table of contents useful:

• Keep heading text clear and unique so anchors stay predictable
• Limit the table to two levels, since deeper nesting becomes noise
• Place the table near the top, right after the introduction
• Re check links after renaming any heading

For more on writing clean headings and structuring documents, see our guide on how to write in Markdown.

Build Yours in Seconds

A table of contents turns a wall of text into a navigable document. Open edtr.md, paste in your headings, write a short list of anchor links, and click each one in the live preview to confirm it jumps to the right place. Once it works, you have a clean, clickable map that ships with your document anywhere Markdown is read.