2026-09-01 · 5 min read · Rahul Chitturi
- markdown
- documentation
- debugging
A relative Markdown link can work in an editor preview and fail after the file moves to a documentation site, package registry, or PDF export. Each renderer chooses a base URL and may rewrite repository paths differently.
Case-insensitive local filesystems hide another common failure: README.md links to ./images/Diagram.png while Linux CI contains diagram.png.
Identify the rendering base
Determine the source document path, output URL, repository root, and renderer before editing links. Resolve links from the document location unless the publishing system explicitly defines another base.
- Check path case and percent-encode spaces or special characters
- Avoid workstation-only absolute file paths
- Verify heading-anchor rules for the target renderer
- Include linked assets in package and deployment outputs
Choose portable link targets
Use relative paths for versioned files that move together and absolute HTTPS URLs for stable external destinations. Root-relative links can fail outside one website host, while branch-specific repository URLs become stale.
PDF and offline exports may not embed remote images. Decide whether the artifact must remain self-contained, and keep meaningful alt text even when an image fails to load.
A Flashman workflow
Use the Markdown editor and viewer to preview local structure, Markdown to PDF to check exported assets, and URL tool to inspect encoded external destinations without uploading document content.
Run a link check in the publication environment and test renamed files, nested documents, duplicate headings, images, fragments, offline export, and Linux case sensitivity.