← All text tools

Table of Contents from Headings

Build a linked table of contents from the headings of a Markdown document, using GitHub anchor rules, as a bullet or numbered list.

  • Free
  • No sign-up
  • Works on any device

About Table of Contents from Headings

Long README files and documentation pages are easier to navigate with a linked table of contents. This generator scans a Markdown document for headings written with # marks or underlined with = and -, ignores anything inside code fences, and links each entry to its anchor using GitHub's rules: lower case, punctuation removed, spaces turned to hyphens, and repeated titles numbered -1, -2. Choose the shallowest and deepest heading level to include and a bullet or numbered list, then paste the result under your title.

How to use Table of Contents from Headings

  1. Paste your Markdown document into the box.
  2. Choose the heading levels to include and a bullet or numbered list.
  3. Copy the table of contents and paste it near the top of your file.

Why use this tool?

Also known as

Frequently asked questions

How are the anchor links made?

The heading text is lower-cased, characters other than letters, digits, hyphens and underscores are dropped, and spaces become hyphens. So "Usage & API" links to #usage--api.

What happens with two headings that have the same title?

GitHub gives the second one the suffix -1, the third -2, and so on. The tool counts every heading in the document the same way, so the links match what GitHub renders.

Do the anchors work outside GitHub?

Many renderers use similar rules, but not all. GitLab and some static site generators differ in details such as handling of accents, so test a link after publishing.

Is Table of Contents from Headings free?

Yes. Table of Contents from Headings on Toolipedia is free to use, with no sign-up and no watermark.

Is it safe to use?

Yes. Everything is worked out in your browser, and nothing you enter is sent to our server.

Does it work on my phone?

Yes. It works in any modern browser on Android and iPhone, as well as on tablets and computers. There's nothing to install.

Do I need an account?

No. Just open the page and use the tool. There's no sign-up and no email needed.

Can I put Table of Contents from Headings on my own website?

Yes. Use the Embed on your site button under the tool to copy a short piece of code and paste it into your page. It is free, needs no account, and the tool keeps working inside your page.

Related tools