How to Create a Table of Contents in Markdown

Long Markdown documents can become difficult to navigate when they contain many sections, setup steps, examples, and FAQs.

A table of contents (TOC) solves this by creating a list of clickable links that jump directly to different sections. It is commonly used in GitHub README files, documentation websites, technical guides, tutorials, and knowledge bases.

In this guide, you will learn how Markdown table of contents links work, how to create them manually, and how to generate them automatically with the free Markdown TOC Generator on MDConvertHub.

What is a Markdown table of contents?

A Markdown table of contents is a list of links that point to headings inside the same document. Instead of scrolling through a long file, readers click a section name and jump directly to it.

Example:

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

When someone clicks one of these links, the page scrolls to the matching heading.

Why use a table of contents?

A TOC improves navigation and makes large documents easier to read. It is especially useful for:

• GitHub README files
• Software documentation
• Technical tutorials
• Product guides
• Internal knowledge bases
• Long Markdown articles

Many open-source projects place a TOC near the top of the README so users can quickly find installation steps, usage examples, configuration options, and FAQs.

Basic Markdown TOC example

Imagine your document contains these headings:

# Introduction

## Installation

## Usage

## Configuration

# FAQ

You can create a table of contents like this:

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

Each link points to a heading inside the same document.

How Markdown heading links work

Most Markdown platforms automatically create anchor IDs from headings.

For example, # Installation Guide becomes #installation-guide.

Rules usually include:

• Convert text to lowercase
• Replace spaces with hyphens
• Remove unsupported special characters

So # Getting Started becomes #getting-started.

Need one link for a single heading? Use the Markdown Anchor Link Generator to build the correct [text](#anchor) syntax without guessing.

How to create a TOC manually

Step 1: Add headings

Create the structure of your document using headings:

# Project Name

## Installation

## Usage

## License

Step 2: Create matching links

Add links that point to those headings:

- [Installation](#installation)
- [Usage](#usage)
- [License](#license)

Step 3: Place the TOC near the top

Most README files place the table of contents below the introduction so readers can navigate immediately.

Automatic Markdown TOC generation

Manually creating TOCs works for small documents, but large files can contain dozens of headings.

A TOC generator can automatically:

• Detect headings
• Create anchor links
• Build nested section structures
• Output a complete table of contents instantly

Paste your Markdown into the free online TOC tool, review the nested list, and copy it to the top of your README or doc. This is especially useful for documentation that changes frequently.

GitHub README table of contents example

Many GitHub repositories use a structure like this:

## Table of Contents

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

With matching headings in the body:

# Installation

# Usage

# Configuration

# Contributing

# License

This creates a simple navigation menu inside the README.

Common TOC mistakes

Incorrect anchor names

The anchor must match the heading GitHub generates.

Incorrect link: [Install](#install) for heading # Installation

Correct link: [Installation](#installation)

Missing hyphens

Multi-word headings use hyphens: #getting-started, not #gettingstarted.

Not updating the TOC

If headings change later, update the table of contents too — or regenerate it from the latest Markdown.

Table of contents vs anchor links

An anchor link points to one section. A table of contents is a collection of anchor links organized as a navigation list.

Anchor link example:

[Usage](#usage)

TOC example:

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

Related tools

• Generate TOC from headings — paste Markdown and copy a nested table of contents
• Markdown Anchor Link Generator — create one section link at a time
• Markdown Editor — write Markdown with live preview
• Markdown cheat sheet — syntax reference for headings and lists
• Markdown to HTML — publish Markdown as HTML for the web

FAQs

What is a Markdown table of contents?

A Markdown table of contents is a list of links that jump to headings within the same document.

Do Markdown TOCs work in GitHub?

Yes. GitHub automatically generates heading anchors you can use inside a table of contents.

Why should I use a TOC?

A TOC improves navigation and helps readers move through long documents more easily.

Can I create a TOC automatically?

Yes. Paste your Markdown into a TOC generator to detect headings and create linked navigation instantly.

What is the difference between a TOC and an anchor link?

An anchor link points to a single section. A TOC combines multiple anchor links into one navigation menu.

Final thoughts

A table of contents is one of the simplest ways to improve navigation in Markdown documents. Whether you are writing a GitHub README, project documentation, tutorial, or knowledge base article, a TOC helps readers find information faster.

Paste your document into the TOC tool, copy a ready-made navigation list, and place it at the top of your README. More guides are on the MDConvertHub blog.