MDUtil

Markdown Table of Contents Generator

Paste a README or any Markdown document and get a linked table of contents that works on GitHub, GitLab and in VS Code. Nothing is uploaded.

Markdown

221 characters25 lines
- [Getting Started](#getting-started)
  - [Install](#install)
  - [First run](#first-run)
- [Configuration](#configuration)
  - [Sync & storage](#sync--storage)
  - [Photos](#photos)
- [FAQ](#faq)
- [Usage](#usage)
- [Usage](#usage-1)

What it handles

GitHub's anchors
Links use the anchors GitHub creates: lowercase, spaces as hyphens, punctuation dropped, and -1, -2 added to repeated headings.
Any range of levels
List only ## and ###, or any range from level 1 to 6; the nesting follows the heading levels.
Updates in place
Put <!-- toc --> and <!-- tocstop --> in the file, and the table of contents is written between them each time.
Code ignored
Lines that start with # inside code blocks are not taken for headings.
Clean link text
Bold text, code and links inside headings become plain text in the table of contents.
Chinese and Japanese headings
Headings in other scripts keep their characters in the anchor, as GitHub does.

How GitHub creates heading anchors

GitHub gives every heading an anchor made from its text: letters are lowercased, spaces become hyphens and punctuation is removed. A repeated heading gets -1, -2 and so on.

HeadingLink
## Getting Started#getting-started
## Sync & storage#sync--storage
## 安装#安装
A second ## Usage#usage-1

Link to a heading by its anchor, as in [Install](#install). GitLab and VS Code create anchors the same way.

Questions and answers

How do I add a table of contents to a Markdown file?

Paste the file above and copy the table of contents into it, or put <!-- toc --> and <!-- tocstop --> where it belongs and copy the whole document from the second tab.

Does GitHub make a table of contents automatically?

GitHub shows an outline of a README's headings from the outline button above the file, but it does not add one to the file. A written list of links also works on other sites, in editors and in exported documents.

How do I link to a heading in Markdown?

Use the heading's anchor: [Install](#install). The anchor is the heading text in lowercase, with spaces turned into hyphens and punctuation removed.

How do I keep the table of contents up to date?

Keep the <!-- toc --> markers in the file and paste the document here again after editing; the list between them is replaced. In VS Code, the Markdown All in One extension can update it on save.

Why does a link not jump to its heading?

Sites build anchors differently. These links follow GitHub, GitLab and VS Code; Bitbucket adds markdown-header- in front, and some site generators use their own rules.

Is my document uploaded anywhere?

No. The table of contents is built in your browser, so the document never leaves your device.