Linking & paths

Two backends sit behind rig.dashecorp.com. One works flawlessly under the path-prefix proxy. The other doesn't. The difference is how each renders asset URLs.

The two backends

Backend	Generator	Asset path style	Behaviour under /prefix/ proxy
docs.rig.dashecorp.com	MkDocs Material	Relative — assets/stylesheets/main.css	✅ proxies cleanly: browser asks rig.dashecorp.com/docs/assets/..., Worker strips /docs, hits docs.rig.dashecorp.com/assets/... → 200
research.rig.dashecorp.com	Astro Starlight	Absolute — /_astro/common.CODNvO0c.css	❌ browser asks rig.dashecorp.com/_astro/..., Worker has no route for /_astro/ (only /research/ is mapped), → 404

Result: visit rig.dashecorp.com/docs/, everything renders. Visit rig.dashecorp.com/research/, you get the HTML but every CSS/JS/image 404s.

Why MkDocs is fine

MkDocs Material defaults to use_directory_urls: true and emits relative links: <link rel="stylesheet" href="assets/stylesheets/main.css">. The browser resolves that against the current page, so when you're on rig.dashecorp.com/docs/components/rig-conductor/, the asset URL becomes rig.dashecorp.com/docs/assets/stylesheets/main.css. The Worker matches the /docs/ prefix and proxies. Everything just works.

Why Astro breaks

Astro builds with the assumption that the site lives at the root of its hostname. Its compiler emits:

<link rel="stylesheet" href="/_astro/common.abc.css">
<script type="module" src="/_astro/page.def.js"></script>

Under rig.dashecorp.com/research/, the browser turns those into rig.dashecorp.com/_astro/... — outside any of the Worker's routes. The Worker default-404s.

Fixes (pick one for each affected backend)

A. Subdomain — fastest, no source changes

Move the broken backend onto its own subdomain so it serves at the root again:

• research.rig.dashecorp.com → research.rig.dashecorp.com (Pages Custom Domain in CF)
• Remove /research/* from the Worker route table; landing-page link points at the subdomain.

Pros: zero source changes, same content. Cons: two hostnames in the wild instead of one.

B. Rebuild with base — keeps single hostname

Set base: "/research" in astro.config.mjs (or the Starlight config) and rebuild. Astro then emits /research/_astro/... and the Worker proxies it normally.

Pros: one hostname, one URL pattern. Cons: requires a rebuild + redeploy of the Astro source; inter-page links inside the Astro site need to be re-checked.

Recommendation

For now, A for /research/ (it's a known-broken path that just needs to start working). When/if a third Astro-style backend comes along, reconsider B as the standard.

Cross-page links inside the aggregator

The aggregator imports each component repo's docs/*.md verbatim. Internal links inside those files use repo-local paths like [architecture](architecture.md). Those work because all of a repo's docs end up in the same components/<repo>/ directory.

Cross-repo links ([conductor's API](../rig-conductor/api.md)) also work — same components/ parent.

Links from a component doc up to rig-level pages (architecture, whitepaper) don't work today; they should be written as /architecture/current/ (absolute paths starting from the docs root) so MkDocs resolves them site-relative.

The MkDocs --strict flag would catch all of this; we currently disable it because legacy docs in rig-gitops itself have broken cross-links (cleanup tracked separately). Until then, broken-link reports are surfaced as build warnings, not errors.