How to Create a Table of Contents in Markdown

A well-structured Markdown document is easy to write, but it can become difficult to navigate as it grows. Installation guides, API documentation, tutorials, and project READMEs often contain dozens of sections, forcing readers to scroll until they find the information they need.

A table of contents (TOC) solves this problem by turning your headings into clickable navigation links. Instead of searching through a long document, readers can jump directly to the section they want.

In this guide, you'll learn when you should add a table of contents, how Markdown heading links work, how to create a TOC manually, and when it's better to generate one automatically. Whether you're maintaining a GitHub repository or writing technical documentation, these best practices will help you build cleaner, easier-to-navigate Markdown documents.

When should you add a table of contents?#

Not every Markdown file needs a table of contents.

For short notes or simple README files with only a few headings, adding a TOC usually creates unnecessary clutter.

A table of contents becomes useful when readers need to navigate between multiple sections quickly.

It's a good idea to add one if your document includes:

• Installation instructions
• Usage examples
• Configuration steps
• API documentation
• Troubleshooting sections
• Frequently asked questions
• Multiple chapters or tutorials

Most open-source projects place a TOC near the top of their README so contributors and users can quickly jump to installation, usage, configuration, or contributing guidelines.

Quick tip: As a general rule, if your document has five or more main sections, adding a table of contents usually improves navigation.

How a Markdown table of contents works#

A Markdown table of contents is simply a collection of links that point to headings within the same document.

For example, if your document contains these headings:

# Installation

# Usage

# Configuration

# FAQ

You can create a navigation menu like this:

- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [FAQ](#faq)

Each link points to the matching heading further down the page. When someone clicks a link, the page automatically scrolls to that section.

Unlike website menus, you don't need JavaScript or custom code. Most Markdown platforms—including GitHub and many documentation tools—generate these heading anchors automatically.

Create your first Markdown TOC#

Creating a table of contents manually only takes a few steps.

Step 1: Finish your document structure#

Before creating a TOC, write the main sections of your document.

For example:

# Project Name

## Installation

## Usage

## Configuration

## Contributing

## License

Having your headings in place first makes it much easier to build accurate navigation links.

Step 2: Create matching anchor links#

Next, create a list of links that matches each heading.

- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

The text inside the brackets is what readers will see, while the value inside parentheses points to the corresponding heading.

Step 3: Place the TOC near the top#

The most common location is immediately below your project introduction or short description.

This allows readers to navigate the document before they begin reading, which is especially helpful for long technical documentation and open-source projects.

How GitHub creates heading links automatically#

One of the reasons Markdown tables of contents are so easy to build is that platforms like GitHub automatically generate anchor links for headings.

When you create a heading, GitHub converts it into a URL-friendly anchor that can be linked from anywhere in the same document.

Heading	Generated anchor
# Installation	#installation
## Getting Started	#getting-started
## API Reference	#api-reference
## Frequently Asked Questions	#frequently-asked-questions

In most cases, the conversion follows a few simple rules:

• All letters become lowercase.
• Spaces are replaced with hyphens (-).
• Most punctuation and special characters are removed.
• The generated anchor matches the visible heading text.

This makes creating internal navigation straightforward because you only need to reference the generated anchor.

Quick tip: If you're unsure what an anchor will look like, use the Markdown Anchor Link Generator instead of guessing.

Manual vs automatic TOC generation#

There are two common ways to create a Markdown table of contents.

Manual TOC#

A manual TOC is written by hand using Markdown links.

Best for:

• Small README files
• Short documentation
• Tutorials with only a few sections
• Documents that rarely change

Advantages:

• Complete control over the order.
• Easy to customize.
• No additional tools required.

Limitations:

• Must be updated whenever headings change.
• Easy to forget links after editing.
• Can become time-consuming for large documents.

Automatic TOC#

A TOC generator scans your Markdown document, finds every heading, and builds the navigation for you.

It's the better option when you're working with:

• Large documentation projects
• Long tutorials
• API documentation
• Knowledge bases
• Frequently updated README files

Instead of manually checking every heading, paste your Markdown into the Markdown TOC Generator, review the generated navigation, and copy it back into your document.

This approach saves time and reduces the chance of broken links.

Best practices for a better Markdown TOC#

A table of contents is most helpful when it's simple and easy to scan.

Follow these best practices:

• Place the TOC near the beginning of the document.
• Write clear, descriptive headings.
• Keep heading levels consistent throughout the document.
• Include only major sections—avoid listing every minor subsection.
• Update the TOC whenever headings are renamed.
• Test a few links after publishing your document.

A clean TOC should help readers find information quickly without overwhelming them with dozens of links.

Best practice: If your README only has three or four sections, you probably don't need a table of contents. Adding one is most valuable for documents that readers will regularly navigate rather than read from start to finish.

Common table of contents mistakes#

Even experienced Markdown users occasionally create TOCs that don't work as expected.

Using the wrong anchor#

The anchor link must match the generated heading exactly.

• ❌ #install
• ✅ #installation

Forgetting hyphens#

Headings with multiple words use hyphens.

• Heading: Getting Started
• Correct anchor: #getting-started

Renaming headings without updating the TOC#

If you change a heading after creating the table of contents, remember to update the corresponding link as well.

Automatic TOC generators make this much easier because they regenerate the navigation from the latest version of your document.

Creating a TOC before finishing the document#

Many writers build the TOC first and then continue editing headings later.

A better workflow is:

1. Finish the document structure.
2. Review all headings.
3. Generate or update the TOC.
4. Test the links once before publishing.

This reduces maintenance and prevents broken navigation.

Table of contents vs anchor links#

A table of contents and an anchor link are closely related, but they aren't the same thing.

An anchor link takes readers to one specific section of a document, while a table of contents combines multiple anchor links into a navigation menu.

Table of contents	Anchor link
Contains multiple links	Links to one heading
Helps readers navigate long documents	Jumps to a specific section
Usually placed near the top of a document	Can appear anywhere in the content
Best for README files, documentation, and guides	Best for cross-referencing important sections

For example, this is a single anchor link:

[Installation](#installation)

A table of contents simply groups many of these links together to create a complete navigation section.

Where Markdown TOCs work best#

A table of contents is useful anywhere readers need to move between sections quickly.

Some of the most common use cases include:

Document type	Why a TOC helps
GitHub README	Quickly access installation, usage, configuration, and contributing sections.
Technical documentation	Navigate long guides without excessive scrolling.
API documentation	Jump directly to endpoints, authentication, or examples.
Tutorials	Move between lessons or chapters easily.
Knowledge bases	Help teams find information faster.
Product documentation	Improve navigation across setup, features, and troubleshooting.

As your document grows, a TOC becomes less of a convenience and more of a usability feature.

Final thoughts#

A table of contents is one of the easiest ways to improve the usability of a Markdown document. It helps readers find information faster, makes long README files easier to explore, and gives technical documentation a more professional structure.

For smaller documents, creating a TOC manually is often enough. As your documentation grows, generating it automatically saves time and helps keep links accurate whenever headings change.

Whether you're maintaining an open-source project, writing product documentation, or publishing tutorials, a well-organized table of contents makes your content easier to navigate and easier to maintain.