---

id: 8882516a-8e3e-4197-978e-c3718eaf3854 title: Relative markdown links/images and heading anchors 404 in generated pages state: closed labels:

• area:render assignees: [] milestone: null created: 2026-10-27T18:40:23.190333659Z updated: 2026-10-27T19:53:10.528735901Z

---

Problem

Markdown links and images are rendered verbatim relative to the generated page. They point at source paths that do not exist in dist/, so README, file-page, wiki, release, issue, and PR links/images fail.

Verified fixture:

README.md: [guide](docs/guide.md)
index.html: href="docs/guide.md"        -> /docs/guide.md (404; page is /files/docs/guide.md.html, raw is /raw/docs/guide.md)
files/docs/guide.md.html: [peer](peer.md) -> /files/docs/peer.md (404; page is /files/docs/peer.md.html)
wiki/home.md.html: [other](other.md)      -> /wiki/other.md (404; page is /wiki/other.md.html)

Headings are emitted without ids, so README/wiki table-of-contents #section links also do not resolve.

Impact

Primary README navigation, wiki navigation, and relative images are broken on every target, including serve and Pages. This is core documentation UX, not just cosmetics.

Fix

Rewrite relative markdown destinations/images against the current page context (README root, file path, wiki path, release path; /files/...html, /raw/..., /wiki/...html as appropriate), or explicitly document that only absolute/raw links work. Add heading IDs if anchor navigation is expected. Add fixtures covering README, nested file page, wiki, and release body links.