Skip to content
Back to blog
Wednesday, November 18, 2026

How to Make a Markdown Table of Contents for a GitHub README

Create a clickable contents list for a GitHub README. Copy a nested example, check anchors for duplicate headings and repair links after edits.

How to Make a Markdown Table of Contents for a GitHub README

Put a bulleted list near the top of your README. Use a link such as [Quick start](#quick-start) to point to the heading ## Quick start. The text in brackets is what readers see. The part after the hash tells GitHub which heading to open.

GitHub also builds an Outline from the headings in a rendered Markdown file. Use that when you are scanning someone else's README. Write a table of contents into your file when you want readers to see a short list of the most useful sections as soon as they open it. GitHub's guide to README files

Copy a complete README with a table of contents

This sample has one nested entry and two headings with the same name. Paste it into a Markdown file to see how all four links are written.

# Field Notes

## Contents

- [Quick start](#quick-start)
  - [Import a notebook](#import-a-notebook)
- [Examples for writers](#examples)
- [Examples for reviewers](#examples-1)

## Quick start

Open a notebook and add your first entry.

### Import a notebook

Choose an existing folder of Markdown notes.

## Examples

Writers can group entries by trip.

## Examples

Reviewers can scan entries by date.

The indented Import a notebook item sits under Quick start, mirroring the relationship between the H3 and H2 headings. Both sections called Examples keep their original headings. The link labels tell readers which audience each section is for, and the fragments point to different targets.

Find the heading's real anchor

For a simple heading, GitHub lowercases the letters and turns spaces into hyphens. It strips formatting marks from headings and removes punctuation such as a question mark. If the generated anchor repeats, GitHub adds a numeric suffix. In the sample, the first Examples is #examples and the second is #examples-1. GitHub's section link rules

You can skip guessing. Render the file in GitHub, hover over the heading and click the link icon beside it. Copy the fragment from the browser address and use it in the contents list. This is especially handy when the heading contains punctuation, inline formatting or non-ASCII characters. For a link from a different Markdown file in the same repository, put the relative file path in front of the fragment, as in [Quick start](README.md#quick-start) when the two files share a folder.

What happensWhat to check
The link stays at the top of the fileCheck that the fragment begins with a hash and matches the one copied from the rendered heading.
Both entries jump to the first Examples sectionCopy the second heading's fragment. In this sample it ends in -1.
The jump stopped working after an editCheck the rendered anchor after renaming or reordering a heading. Update any links that pointed to the old anchor.
A subtopic appears on the same level as its parentIndent its bullet and check the rendered list. The heading level and the list indentation are separate.
A link works on one site and fails on anotherCopy the heading anchor from the site where readers will open the file.

After editing, click each entry in the rendered README. Check that it lands on the intended section, especially when duplicate headings were moved. A short contents list can start with the sections people need to act on, such as setup, usage and troubleshooting. Add subtopics when they help readers skip a long section.

Share the layout as an image

The PNG below was downloaded from the Markdown2Image editor using the same source. It shows heading levels and the nested list, which can be useful in a slide reviewing documentation structure. Put the clickable README link alongside the image so readers can open the document and jump to a section. Preview the sample in Markdown2Image

Rendered README with a contents list, a nested entry and two Examples sections

Open the original PNG