This adds a remark plugin that transforms .md links (e.g., [text](other.md))
into clean URLs (e.g., other/) that work in the built Starlight site while
keeping the original .md links functional on GitHub.
Key design decisions:
1. Uses relative paths instead of absolute paths. This ensures links work
regardless of the base path configuration (e.g., --base /starlight/).
Absolute paths like /glossary/ would break when deployed at a non-root
base path.
2. Accounts for Starlight's trailing slash URL behavior. Pages like
guides/divergence.md are served at /guides/divergence/, which browsers
treat as a directory. For non-index files, the plugin prepends ../ to
counteract this, so a link to ../glossary.md becomes ../../glossary/
(which correctly resolves to /glossary/ from /guides/divergence/).
3. Wrapped in a Starlight plugin (starlight-strip-md-extension.mjs).
This is required because Starlight overrides the markdown.remarkPlugins
config for content collection .md files. Plugins in the top-level
markdown config only run on .mdx files. The Starlight plugin wrapper
hooks into Starlight's integration system to ensure the transformation
runs on all content collection markdown files.
This change adds a new docs deployment to /starlight/, and that's rendering the
documentation via Starlight: https://starlight.astro.build/
mkdocs is no longer being maintained, and we'd like to move away from it for
that reason. We've chosen starlight for two main reasons: first, it has a goal
of minimizing JavaScript on the front end, and that aligns with our priorities.
Second, it is based on Astro.js, which would also be a good tool for writing a
basic marketing site. The overall sentiment from community in the Discord was
leaning towards Astro when we were talking about this.
After a few days of checking out the new docs and making sure that things are
good, we can move to making this the default.
Part of #7959.
