Where should a README table of contents go?

Place it after the project summary and before detailed instructions. Readers can then see the available sections without passing the navigation block.

Should every heading appear in the table?

No. Include major sections and useful subsections. Listing every small heading can make the navigation harder to scan.

Why does a heading link not work?

The renderer may use different anchor rules, or the heading may contain punctuation, duplicate text, or a changed spelling. Check the rendered target.

Can a generator update the table automatically?

Yes, a generator can create links from headings. Review the result after edits because generated anchors and duplicate headings still require testing.

Add a Table of Contents to a README

Add a README table of contents by linking each entry to a heading anchor. Use a list near the beginning of the file, keep labels short, and update links when headings change. GitHub creates anchors from most Markdown headings by lowercasing text, replacing spaces with hyphens, and removing many punctuation marks. A table of contents works best when it covers the main sections without listing every small subsection.

Choose headings and link targets

Start with the README headings that help a new reader find information quickly. Common entries include Installation, Usage, Configuration, Contributing, Testing, and License. Use one heading level for major topics, usually level two headings written with two number signs. Add a nested list only when the document has several meaningful subsections. Each link target must match the heading anchor generated by the publishing system. For a heading such as ## Install on Linux, the usual GitHub target is #install-on-linux. Punctuation can change the result, so check the rendered page instead of guessing. Avoid duplicate heading text when possible. Duplicate headings can produce numbered anchors, which makes manually maintained links harder to predict.

Write a maintainable Markdown list

Place the table of contents after the short project summary and before long instructions. Use descriptive link text rather than repeating raw URLs. A simple list is easy to scan and easy to edit. For nested items, indent consistently with spaces and keep the hierarchy aligned with the headings. Do not include the table of contents inside itself. You can label the block with a heading such as ## Contents, but that heading should not usually appear as its own entry. Keep entries in document order. If the README has generated sections, mark the generated area clearly and avoid editing it by hand. A generator can reduce mistakes, but review its output after changing heading names, punctuation, or heading levels.

Test links before publishing

Render the README in the service where readers will view it, then click every table of contents link. Check links from different locations if the file appears on a project page, package page, or documentation site. Some Markdown processors use different slug rules, so a link that works on GitHub may not work in another renderer. Confirm that headings are visible, unique, and in the expected order. Keep the table short when the README is short. For a long README, consider separate guides instead of creating a deeply nested navigation list. Update the table whenever a heading is renamed, removed, or moved. A code review checklist can include a heading-link check so documentation changes do not leave stale anchors.

How do you do it step by step?

1List the major README headings in the order that readers should encounter them.
2Convert each heading into the anchor format used by the target Markdown renderer.
3Add a Markdown list near the top of the README and link each label to its anchor.
4Render the file, click every entry, and correct links affected by punctuation or duplicate headings.
5Review the table whenever you rename, remove, or reorder a heading.

Working example

This example links a short contents list to three README sections.

Input

## Contents
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)

## Installation
Install the package with your package manager.

## Usage
Run the command with a project path.

## Contributing
Open an issue before submitting a large change.

Result

The rendered Contents list shows three clickable entries. Each entry moves the reader to the matching heading on the same page.

Test the anchors in the target renderer. Anchor rules can differ between GitHub and other Markdown processors.

Frequently asked questions

Where should a README table of contents go?: Place it after the project summary and before detailed instructions. Readers can then see the available sections without passing the navigation block.
Should every heading appear in the table?: No. Include major sections and useful subsections. Listing every small heading can make the navigation harder to scan.
Why does a heading link not work?: The renderer may use different anchor rules, or the heading may contain punctuation, duplicate text, or a changed spelling. Check the rendered target.
Can a generator update the table automatically?: Yes, a generator can create links from headings. Review the result after edits because generated anchors and duplicate headings still require testing.