Markdown Heading Link Repair

Repair a GitHub README table of contents after changing headings

GitHub generates a fragment for each Markdown heading. The fragment can change when you rename a heading, add punctuation or add another heading with the same text. Existing table-of-contents links keep their old destinations until you edit them.

Open Markdown Heading Link Repair

Keep a link to a heading named after a configuration file

Input

[Settings](#settings.json)

## `settings.json`

## `settings.json`

Output

[Settings](#settingsjson)

## `settings.json`

## `settings.json`

The first heading gets the fragment settingsjson. The second gets settingsjson-1. Use the heading list to choose which occurrence your link should reach.

Check the result

  1. Open the whole document so the same-file headings are available and duplicates occur in their original order.
  2. Review shortened link labels. A name such as Settings can point to a number of sections with similar titles.
  3. Follow each repaired link in the final GitHub view. Copy a heading's link from GitHub when the document uses custom markup.

Common problems

Other renderers choose different identifiers

The tool uses the usual GitHub heading fragment rules. A static site theme, another Markdown renderer or a custom extension may use a different rule.

Repeated section titles can hide a destination change

An existing fragment may still be valid even if it now points to a different repeated heading. This check finds missing fragments, so check links to duplicated headings after reordering sections.

Keep linked files separate

A link to another Markdown file or an external site is outside the same-file check. Standard Markdown headings and common quoted HTML anchor attributes are recognized. Unsupported link syntax can need a manual edit.

Using Markdown Heading Link Repair

Open the entire Markdown file

Include the original links and the headings they point to.

Review the heading targets

Use the suggestion or select the heading you meant to link to.

Export the edited Markdown

Open GitHub's preview and follow the links you updated.

Offline use

Open the tool once online and let it finish loading. Use the install option in your browser or Add to Home Screen on iPhone. Reopen the tool to process a new input offline.

References