2026-09-01 · 8 min read
- markdown
- documentation
- portability
Markdown deliberately leaves some link and asset behavior to the renderer. A path resolved beside a README in a repository may resolve from a website route after publication, while a PDF exporter may not fetch remote assets at all.
Portability requires an explicit document root, publication target, and asset policy. Editor preview is useful, but it cannot prove that package registries, static-site generators, repository hosts, and offline exports will choose the same base URL.
Select stable destinations
Use document-relative paths for versioned files that move and release together. Use durable HTTPS URLs for external resources, and avoid local file paths, temporary branches, expiring query strings, or links that depend on one workstation.
- Match filename case exactly for Linux and static hosting.
- Percent-encode spaces and reserved characters in destinations.
- Keep paths within the published or packaged artifact.
- Prefer owned redirect URLs when external destinations may change.
Account for renderer-specific anchors
Heading-to-fragment algorithms differ in punctuation removal, Unicode handling, duplicate suffixes, and case normalization. For important cross-document links, test the generated anchor in every supported renderer or provide an explicit stable identifier when the platform permits it.
Reference-style links can simplify maintenance in long documents, but duplicate or missing definitions need linting. HTML embedded in Markdown is even less portable and may be sanitized or disabled.
Package images and accessible fallbacks
Keep local images near the document or in a clearly versioned asset directory, and ensure build and package manifests include them. Optimize dimensions without making diagrams unreadable at zoom or in PDF output.
- Write alt text that communicates the image's purpose.
- Provide adjacent text for essential diagram conclusions.
- Avoid using an image as the only source of code or commands.
- Define whether offline exports embed or omit remote assets.
Test the publication artifact
Use Flashman's Markdown editor and viewer for local structure, Markdown to PDF for export checks, URL tool for encoded external targets, and diff tool to review path changes after file moves. All processing can remain in the browser.
Run link and asset checks against the built output on a case-sensitive system. Cover nested pages, renamed files, duplicate headings, fragments, redirects, package contents, remote failures, offline viewing, PDF output, and accessibility review.