2026-09-13 · 6 min read · Rahul Chitturi
- markdown
- links
- documentation
A Markdown link can work in one preview and render as plain text or point elsewhere in another. Inline links, reference definitions, angle-bracket autolinks, and extension-based bare URL matching follow different parser rules.
Reference labels can be normalized and definitions can be duplicated or placed far from their use, making a small documentation edit change links unexpectedly.
Identify the exact link form
Reduce the failure to one label, definition, and destination under the production parser. Record enabled extensions and whether raw HTML is allowed rather than assuming every renderer follows GitHub behavior.
- Check balanced brackets and destination parentheses.
- Inspect spaces, escapes, and optional titles.
- Find duplicate normalized reference labels.
- Distinguish autolinks from plain-text URL extensions.
Apply a destination safety policy
Parse rendered destinations and allow only schemes and URL forms appropriate to the publishing surface. Escaping Markdown syntax does not make javascript, data, file, or misleading lookalike destinations safe.
Add rel and target behavior according to product policy, and sanitize raw HTML independently. Link text should describe the destination rather than conceal an unrelated host.
Compare production rendering locally
Use the Markdown editor and viewer for synthetic fixtures, URL tool to inspect destinations, and diff to compare source and rendered-link inventories.
Test collapsed and shortcut references, duplicate definitions, case and whitespace labels, nested punctuation, Unicode, escaped parentheses, titles, bare URLs, email autolinks, unsafe schemes, raw HTML, and renderer upgrades.