---
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 `id`s, 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.