2026-09-17 · 6 min read · Rahul Chitturi
- markdown
- anchors
- documentation
A table-of-contents link can work in one Markdown preview and fail after publishing because heading IDs are usually generated by the renderer, not standardized by core Markdown. Punctuation removal, whitespace folding, case, Unicode, and duplicate headings vary across platforms.
Even a stable slug algorithm cannot preserve a link when an editor renames or reorders duplicate headings without updating inbound fragments.
Capture the rendered ID, not a guessed slug
Render a minimal document with the exact production parser, plugins, sanitizer, and heading-ID extension. Inspect the final HTML ID and URL fragment after every transformation.
- Test repeated headings and their numeric suffixes.
- Check punctuation, emoji, accents, and non-Latin scripts.
- Distinguish percent-encoded URL fragments from decoded IDs.
- Confirm whether raw explicit IDs survive sanitization.
Choose a stable authoring policy
For long-lived documentation, use supported explicit IDs or a generated table of contents tied to the same slugger as rendering. If the platform does not support stable IDs, treat heading renames as link changes and run an internal-link check.
Avoid inserting empty anchors through raw HTML unless the renderer and sanitizer intentionally permit them. Duplicate IDs create ambiguous navigation and accessibility problems.
Test links through the publishing path
Use the Markdown editor and viewer for synthetic headings, URL tool to inspect fragments, and diff to compare rendered ID inventories before and after an edit.
Test duplicate and empty headings, punctuation-only text, inline code, entities, emoji, Unicode normalization, generated tables of contents, explicit IDs, sanitizer changes, renamed sections, and links from other pages.