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 GitHub README files 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 to add a table of contents, how Markdown heading links work, how to create a TOC manually, how to build nested navigation, and when it's better to generate one automatically. Whether you're maintaining a GitHub repository or writing technical documentation, these techniques 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 can create unnecessary clutter.

A table of contents becomes useful when readers need to navigate between multiple sections quickly. Consider adding 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 guideline, if your document has five or more main sections, a table of contents can improve 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 jumps to that section.

Unlike a website navigation menu, you don't need JavaScript or custom code. Many Markdown platforms—including GitHub and documentation tools—automatically generate heading anchors. For more details about Markdown formatting, see our Markdown syntax guide.

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 section headings of your document.

# 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.

## Table of Contents

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

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

Step 3: Create a nested TOC#

If your document contains subsections, you can use nested lists to show the document hierarchy.

For example:

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Basic Usage](#basic-usage)
  - [Advanced Usage](#advanced-usage)
- [Configuration](#configuration)

This makes longer documents easier to scan because readers can see both the main sections and important subsections.

For readability, include only the levels that are useful for navigation. A TOC containing every small subsection can become difficult to scan.

Step 4: 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 READMEs.

How GitHub creates heading links automatically#

One reason Markdown tables of contents are easy to build on GitHub is that GitHub automatically generates anchor links for headings as part of its GitHub Flavored Markdown rendering.

When you create a heading, GitHub generates a URL-friendly anchor that can be linked from elsewhere in the same document.

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

In many simple cases, the generated anchor follows these general patterns:

• Letters are converted to lowercase.
• Spaces are replaced with hyphens (-).
• Some punctuation and special characters are removed or handled differently.
• The anchor is based on the visible heading text.

Anchor behavior can vary between Markdown platforms, so don't assume every renderer follows exactly the same rules.

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 link syntax.

Best for:

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

Advantages:

• Complete control over the order and structure
• 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 and creates navigation from its heading structure.

It's useful 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 can save time and reduce the chance of broken or outdated 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:

• Write clear, descriptive headings.
• Keep heading levels consistent throughout the document.
• Include major sections and only important subsections.
• Test your links after publishing.

For broader guidance on writing well-structured Markdown, see our Markdown best practices guide.

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

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 heading anchor generated by the platform.

• ❌ #install
• ✅ #installation

Forgetting hyphens#

Headings with multiple words commonly use hyphens in their anchors.

• Heading: Getting Started
• 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 can make this easier because they regenerate navigation from the latest document structure.

Creating a TOC before finishing the document#

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

A better workflow is:

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

This reduces maintenance and helps prevent 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	Can appear anywhere in the document
Best for long documents and guides	Best for cross-referencing specific sections

For example, this is a single anchor link:

[Installation](#installation)

A table of contents simply groups multiple links like these into a navigation section.

Where Markdown TOCs work best#

A table of contents is most useful when readers need to move between multiple sections quickly.

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 docs	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 an increasingly useful navigation 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 and makes long README files and technical documentation easier to navigate.

For smaller documents, creating a TOC manually is often enough. As your documentation grows, generating one automatically with a TOC generator tool can save time and make updates easier.

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 maintain.