fix: make docs links resolve consistently regardless of URL form

[JereSalo]

Problem

Links on the docs site break depending on how the user reaches a page. Docusaurus serves two URL forms, "index" links (they have sublinks) and "leaf" links (they don't have sublinks), and resolves relative links differently for each. When a page is loaded directly via its public URL, the browser appends a trailing /, which makes Docusaurus treat it as an index. When the same page is reached via SPA navigation (clicking a link on another page) the trailing / is sometimes missing, so it is treated as a leaf. As a result, relative links on the page resolve to different absolute paths depending on how the user got there, and many of those paths do not exist.

Examples:

• Index link: https://docs.miden.xyz/builder/get-started
• Leaf link: https://docs.miden.xyz/builder/smart-contracts/cross-component-calls

For cross-component-calls (a real leaf), opening the direct URL renders it as if it were an index, while reaching it via the SPA renders it as a leaf. Using the first method, subsequent relative clicks then resolve to the wrong path. Try accessing the link and then clicking on any highlighted word that takes you to another path, you'll see that if you opened the link as an URL you'll be redirected to an unexisting page.

For get-started (a real index), opening the direct URL works, but reaching it from https://docs.miden.xyz/ renders it as a leaf, breaking relative clicks on the page. Try entering from there and then go to any of the linked guides from there. In the case of the sublink "Installation" the resolved link is going to be https://docs.miden.xyz/builder/setup/installation instead of the correct one that is https://docs.miden.xyz/builder/get-started/setup/installation/. Notice that the former is builder/get-started and the other one is builder/setup/installation.

Goal

Make link resolution independent of the URL shape, and prevent the same issue from being reintroduced by future docs.

Changes

Core fix:

• Normalize internal markdown links to use .md. Before: [Installation](./setup/installation). After: [Installation](./setup/installation.md). Docusaurus resolves .md links from the docs source tree, so they work correctly in versioned docs and do not depend on the URL shape.
• Use docId for <Card> links. Before: <Card href="./setup/installation">. After: <Card docId="builder/get-started/setup/installation">. Docusaurus does not rewrite custom MDX props like href, so Card now resolves docs pages through Docusaurus metadata.

Robustness:

• Add normalize/check scripts (npm run check:doc-links, npm run normalize-doc-links) so new or edited docs cannot reintroduce browser-relative internal links.
• Run normalization during deploy. CI imports docs from other Miden repos, so the deployed site needs the cleanup step after aggregation.

A trailing / no longer matters: links resolve consistently because they are referenced through Docusaurus' source-tree resolver instead of browser-relative URLs.

I tested it locally and both edge cases I mentioned worked perfectly fine.

[JereSalo]

TLDR: Some links are broken/flaky in the miden docs, a good example to replicate this is by going to https://docs.miden.xyz/builder/smart-contracts/cross-component-calls/ and then on the first paragraph clicking on a relative link, it'll be broken. This is one of the edge cases this PR aims to fix, but at a structural level so that we fix it in all the docs. For more info read description.

[BrianSeong99]

Thanks for digging into this @JereSalo — the repro is spot on. I ran a full-ingestion build of main today and this flaky-link problem is very much live (e.g. the miden-bank index's relative links resolving to /miden-bank/miden-bank/*, and .md-suffixed relative links into the reference section). Definitely worth fixing.

Heads up before you continue: the Core Concepts → Reference rename (#306) just merged. It moved docs/core-concepts/ → docs/reference/ and touched a lot of the same files, so this branch will now conflict heavily with main.

Could you rebase onto the latest main and slim the scope so it's easy to review? Ideally:

• the .md link normalization + <Card docId> conversion on the current docs,
• the normalize-doc-links / check:doc-links scripts plus the deploy/CI guard.

I'd suggest dropping the bulk edits to the frozen versioned_docs/ snapshots for now — that's most of the ~200-file diff and the biggest source of conflicts. We can regenerate those with your script in a follow-up if we decide we want them. Keeping this PR to current docs + the tooling makes it very mergeable.

Really appreciate the insight and the script — happy to review as soon as it's rebased.

[JereSalo]

Hey @BrianSeong99! Thanks for the review, and sorry for the delay.

Rebased onto latest main and slimmed the scope as you asked. Dropped the versioned_docs/ edits, I'll regenerate those with the script in a follow-up.

I added a check-doc-links PR job that fails on reintroduced browser-relative links, since the deploy step only heals them at build time.

Let me know if you'd like anything else!