Markdown Heading IDs
Last updated: 2026-10-14
Heading IDs Common extension
An extension. Append {#custom-id} to a heading to set the anchor, then link within the page via [text](#custom-id). The infrastructure for TOCs, FAQ back-links and cross references.
| Group | GFM Extensions |
|---|---|
| Spec level | Common extension |
| Spec version | CommonMark 0.31.2 + GFM |
📝 Syntax
## Heading {#anchor}
[link text](#anchor)▶ Live Example
Edit Markdown on the left, see the result on the right
💡 Key points
ℹ️ Note Without {#id}, renderers slugify the heading text — rules vary for CJK, so set explicit ids in long docs.
⚠️ Warning GitHub ignores {#id} syntax but still auto-generates anchors from heading text.
❓ FAQ
Q How are anchors auto-generated?
A Lowercase, spaces to hyphens, punctuation stripped; CJK rules vary by renderer.
Q Is it supported on this site?
A Tutorial pages get auto anchors from the builder; markdown-it-anchor is optional.
Q Can jumps scroll smoothly?
A Add CSS scroll-behavior: smooth — nothing needed at the Markdown layer.
📚 See also
HeadingsCommonMark core