Menu

Search toolsChangelog

to move to openDescribe the problem, not the tool

Guide answer

Why Markdown heading links differ between websites

The Markdown grammar says which text is a heading; it does not standardise the HTML id a host invents for that heading. Platforms can remove punctuation differently, treat Unicode differently and choose different suffixes for duplicates. If portable links matter, insert explicit unique ids and link to those exact values, then verify that the destination permits raw HTML anchors.

What to take away
  1. ATX and Setext heading syntax is standardised independently from a host's generated URL fragments.

  2. Code fences must be recognised before heading-looking example lines are scanned.

  3. Explicit ids remove slug guesswork but still depend on a renderer that does not sanitise authored anchors away.

The full explanation

A Markdown heading is portable structure; its automatic URL fragment is not. Hosts make different choices about punctuation, Unicode, duplicate suffixes and raw HTML. A table of contents becomes more predictable when its target ids are explicit and its assumptions are visible in the document. Read the complete guide for the reasoning, examples and definitions behind this answer.

Use the idea

Sources