Rewriting Relative Markdown Links and Heading Anchors for Confluence Storage XHTML

Updated 2026-11-03

Direct Answer: Confluence Cloud Storage XHTML does not resolve POSIX relative file paths (.md) across wiki pages. To preserve internal navigation, a compiler must normalize POSIX paths relative to each source file directory, map target paths to their Confluence page titles inside the target space key, and emit ac:link elements with ri:page and ac:anchor attributes.

POSIX Path Normalization & Traversal Guards

Every outbound Markdown link is normalized against the directory of the source Markdown file. Links that traverse above the repository root (../../outside.md) or target missing files are flagged as compiler diagnostics during preflight so broken links never reach Confluence.

Source file: docs/guides/quickstart.md
Raw link:    ../setup.md#install
Normalized:  docs/setup.md (anchor: "install")
Target page: "Setup & Provisioning Guide" (Space: ENG)

Deterministic Attachment Naming Across Subdirectories

Because Confluence attachments live in a flat namespace per page, two images named diagram.png in different folders could collide. DocBrancher prefixes attachment filenames deterministically from their normalized repository path and verifies their SHA-256 digest.

Frequently Asked Questions

What happens if a Markdown file links to an external HTTPS URL?

External HTTPS links are preserved as standard escaped anchor tags, while unsafe schemes such as javascript:, data:, and vbscript: are neutralized by the compiler.