feat: Handle relative files

[zastrowm]

Note: This is targeting the workstream/cms-migration branch - the plan is to do incremental PRs to avoid a single PR with a bunch of code.

The northstar that I'm working towards right now is https://starlight-migration.docs-72e.pages.dev/user-guide/quickstart/overview/

Description

Follow up to #505, #525, #527; part 4/N of the CMS migration.

mkdocs uses relative links to files while Astro by default uses slugs (and does no built-in validation). Instead of requiring slugs everywhere add an override to do a conversion of links based on the or based on the relative path.

An alternative solution would be to do this when converting the docs (e.g. via update-docs.ts) but honestly the devx for linking using slugs everywhere was uglier whereas this is more natural IMHO. Long-term we can probably normalize a bit more, but in the short term this is a good solution.

We also started excluding index.md files from the examples directory as they aren't intended to be pages on the docs - they are only present for readability when on GitHub.

Note

The decision being made here is that we'll modify astro/CMS behavior to allow links to files instead of requiring slugs. For instance instead of requiring:

[custom-tools](/user-guide/concepts/tools/custom-tools/)

we'll also allow:

[custom-tools](../tools/custom-tools.md)

as this provides compatability with mkdocs AND it's easier to reason about.

Why is using slugs a worse devx? Because:

• You need to always remember the trailing slash
• The slug isn't as easy to identify compared to the file path

You can preview the resulting documentation at https://d3ehv1nix5p99z.cloudfront.net/pr-cms-533/user-guide/quickstart/overview/ - notice that links to non-api pages now works (api doc links will be a follow-up). Compared to the previous build links between pages now work!

Review notes

• Until feat: Enable overriding of MDX components by zastrowm · Pull Request #110 · delucis/astro-auto-import is merged, we inline the usage of AutoImport directly into the project - you can review this code, but without the full-context I'm not sure it'll make sense - see the PR for more information
• This PR changes how we load markdown files into the doc collection to exclude index.md files for examples, as those aren't meant to be pages
• "Workflow Failure: Typecheck" is expected; will be addressing that in a future PR
• "Workflow Failure: Deploy Docs Preview (Local PRs) / Deploy Preview " is expected - I need to remove the workflow (will do in a follow-up)

Type of Change

• Content update/revision

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using mkdocs serve
• Links in the documentation are valid and working

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[mehtarac]

/strands review

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-cms-533/user-guide/quickstart/overview/

Updated at: 2026-02-11T15:21:21.607Z