2026-09-13 · 8 min read
- markdown
- links
- security
Markdown supports inline links, full reference links, collapsed and shortcut references, image variants, and angle-bracket autolinks. Many renderers also add a nonstandard extension that recognizes bare web addresses or email-like text.
A source document is therefore not a complete link contract without a named parser, extension set, raw-HTML policy, and destination sanitization step.
Resolve references predictably
Reference definitions can appear away from their uses, and labels undergo parser-defined normalization involving case and whitespace. Duplicate normalized labels need a deterministic policy; relying on whichever definition a new parser chooses can redirect links silently.
- Lint unresolved references before publishing.
- Keep labels descriptive and locally understandable.
- Detect duplicate normalized definitions.
- Test collapsed and shortcut forms explicitly.
Parse destinations with the production grammar
Parentheses, angle brackets, backslashes, spaces, titles, entities, and percent escapes can affect where an inline destination ends. Avoid repairing links with ad hoc regular expressions after Markdown parsing.
Extract rendered links from the same parser configuration used in production and compare their resolved destinations during migrations or dependency upgrades.
Enforce URL and HTML safety
Apply an allowlist of destination schemes and contexts after decoding the renderer's link destination representation. Disallow script-capable or local-resource schemes unless a narrowly trusted product explicitly needs them.
- Sanitize raw HTML under a separate reviewed policy.
- Treat images and links as different loading and privacy surfaces.
- Add external-link attributes according to product policy.
- Make visible link text meaningful and non-deceptive.
Run a renderer compatibility matrix
Use Flashman's Markdown editor and viewer for synthetic documents, URL tool for parsed destinations, diff for source and rendered link inventories, and HTML entities tool for safe encoding fixtures.
Test inline and reference forms, duplicate and unresolved labels, case and whitespace normalization, nested punctuation, escaped destinations, Unicode, titles, bare URLs, email autolinks, unsafe schemes, images, raw HTML, relative URLs, long labels, and every supported renderer upgrade.