2026-09-17 · 8 min read
- markdown
- anchors
- documentation
Core Markdown defines headings but does not define the HTML IDs used for deep links. Hosting platforms and parser plugins supply slug algorithms that differ in punctuation removal, case folding, whitespace, Unicode handling, and duplicate suffixes.
A manually guessed fragment may work in a local preview and fail in production. A generated table of contents can also drift when it uses a different slugger from the final renderer.
Treat heading IDs as renderer output
Document the production parser, heading-ID plugin, sanitizer, and slugger version. Generate the table of contents in the same pipeline or inspect final HTML IDs instead of implementing an approximate regular expression.
- Define duplicate-heading suffix behavior.
- Test punctuation, inline code, entities, emoji, and non-Latin text.
- Reject duplicate explicit IDs.
- Keep URL-fragment encoding separate from slug generation.
Offer stable identifiers for durable links
If documentation has long-lived inbound links, use a supported explicit-ID syntax or a stable section identifier independent of display wording. Verify that the renderer and sanitizer preserve that mechanism.
When explicit IDs are unavailable, treat heading edits as URL changes. Keep compatibility anchors only where the platform permits safe, unique IDs and where maintaining the old link has real value.
Preserve accessibility and document validity
Every ID in the rendered document should be unique. Duplicate IDs make fragment navigation ambiguous and can break relationships used by assistive technology.
Heading hierarchy should reflect document structure rather than being chosen for visual size. Stable anchors do not compensate for skipped levels or headings that provide no meaningful section label.
Run deep-link regression checks
Use Flashman's Markdown editor and viewer for representative documents, URL tool for fragment encoding, diff for rendered ID inventories, and HTML entities tool for text-versus-markup edge cases.
Test duplicate headings, renamed sections, punctuation-only labels, code spans, entities, accents, normalization forms, emoji, right-to-left and non-Latin scripts, explicit IDs, generated tables of contents, sanitizer upgrades, cross-page links, and links from external documentation.