Description
Markdown links between docs are broken in the rendered webui.
Two cases to handle:
-
Relative .md links in source — e.g. [ADR 0018](../decision-records/decisions/0018-smartem-agent-keycloak-auth.md) in docs/agent/authentication.md.
The link is rendered with its raw href, so the browser tries to navigate to …/docs/decision-records/decisions/0018-…md. That path returns 404 because:
- GitHub Pages has no
.md static file there
- The SPA route is
/docs/decision-records/decisions/0018-smartem-agent-keycloak-auth (no .md)
-
Repo-absolute GitHub URLs of the same target — e.g. [ADR 0018](https://github.com/DiamondLightSource/smartem-devtools/blob/main/docs/decision-records/decisions/0018-smartem-agent-keycloak-auth.md).
These currently leave the webui. They should resolve to the in-app route when the target is inside this repo's docs/ tree, so readers stay in the SPA. (External GitHub URLs that don't point at this repo's docs should keep behaving as external links and open in a new tab.)
Suggested approach
A small remark plugin (or a post-processing pass in generate-mdx-docs.ts) that during sync:
- Strips
.md from local relative link targets.
- Detects
https://github.com/DiamondLightSource/smartem-devtools/blob/<ref>/docs/...md and rewrites them to in-app routes.
- Leaves anchors, query strings, and external URLs intact.
Alternative: a custom click handler on the a MDX component that intercepts navigation for local targets. Build-time rewrite is preferred because it keeps the rendered HTML self-describing.
Acceptance
- Clicking
ADR 0018 from /docs/agent/authentication lands on the rendered ADR inside the SPA, no full page reload, no 404.
- The same link written as a repo-absolute GitHub URL behaves identically.
- Anchor links (
#section) and external URLs (e.g. https://keycloak.org) keep working as today.
Description
Markdown links between docs are broken in the rendered webui.
Two cases to handle:
Relative
.mdlinks in source — e.g.[ADR 0018](../decision-records/decisions/0018-smartem-agent-keycloak-auth.md)indocs/agent/authentication.md.The link is rendered with its raw href, so the browser tries to navigate to
…/docs/decision-records/decisions/0018-…md. That path returns 404 because:.mdstatic file there/docs/decision-records/decisions/0018-smartem-agent-keycloak-auth(no.md)Repo-absolute GitHub URLs of the same target — e.g.
[ADR 0018](https://github.com/DiamondLightSource/smartem-devtools/blob/main/docs/decision-records/decisions/0018-smartem-agent-keycloak-auth.md).These currently leave the webui. They should resolve to the in-app route when the target is inside this repo's
docs/tree, so readers stay in the SPA. (External GitHub URLs that don't point at this repo's docs should keep behaving as external links and open in a new tab.)Suggested approach
A small remark plugin (or a post-processing pass in
generate-mdx-docs.ts) that during sync:.mdfrom local relative link targets.https://github.com/DiamondLightSource/smartem-devtools/blob/<ref>/docs/...mdand rewrites them to in-app routes.Alternative: a custom click handler on the
aMDX component that intercepts navigation for local targets. Build-time rewrite is preferred because it keeps the rendered HTML self-describing.Acceptance
ADR 0018from/docs/agent/authenticationlands on the rendered ADR inside the SPA, no full page reload, no 404.#section) and external URLs (e.g.https://keycloak.org) keep working as today.