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.
On this page
01Copy a complete README with a table of contents02Find the heading's real anchorPut 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
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.
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 happens | What to check |
|---|---|
| The link stays at the top of the file | Check that the fragment begins with a hash and matches the one copied from the rendered heading. |
| Both entries jump to the first Examples section | Copy the second heading's fragment. In this sample it ends in -1. |
| The jump stopped working after an edit | Check 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 parent | Indent 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 another | Copy 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.
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