Resolve Markdown document links from source paths

[guanzhousongmicrosoft]

Summary

• resolve relative .md links against the Markdown source file instead of the rendered page URL
• publish sibling, parent-directory, and index.md targets with trailing-slash website routes while preserving queries and fragments
• provide source paths for article, reference, and reference-metadata rendering
• cover the resolver with focused unit tests

This removes the need to rewrite every cross-document Markdown link as an absolute documentdb.io URL and fixes the long-term rendering gap tracked in the docs repository.

Fixesdocumentdb/docs#38

Verification

• npm test (112 tests)
• npm run lint
• tsc --noEmit
• npm run build:next

[guanzhousongmicrosoft]

Both review findings confirmed and fixed in 91594e0.

1. Cross-section api-reference links. Confirmed. The source paths callers pass are already in website space — /docs/reference/... — while an author writes the link against the folder they can actually see in the docs repository, ../api-reference/operators/aggregation/%24limit.md. That resolved to /docs/api-reference/..., which does not exist.

Worth noting why this is the only affected mapping: content.config.json renames exactly one folder on publish (api-reference → reference); the others keep their names, and the articles/ prefix is internal and never reaches a URL. Path depth also matches between the two spaces, so ../-climbing links were already correct. The fix is therefore a single mapping entry rather than a mirror of the config, and the comment says so, so nobody has to re-derive it.

2. NEXT_BASE_PATH. Confirmed. These render as plain anchors, not next/link, so nothing applies the base path for us. Navbar.tsx already calls withBasePath from a client component, so this follows the established pattern rather than inventing one. Worth stating that production deliberately leaves NEXT_BASE_PATH unset — the deploy workflow comments on that at length — so this was latent rather than user-visible, which is what makes it easy to miss.

Coverage — eight new cases: the mapping from an article page and from inside the reference section, a section that is not remapped (guarding against over-eager rewriting), and the base path across a plain route, a mapped route, one carrying a query and fragment, and links the resolver declines to touch. The base-path tests re-import the module after stubbing the environment, since sitePath reads NEXT_BASE_PATH once at module scope.

On verification, honestly:npm ci fails on this machine — the registry proxy 404s on vite@8.2.0 — so the vitest suite is left to CI, and the test wiring above is unproven locally. What I could verify, I did: the resolver was exercised directly under node with type stripping across all thirteen cases, with and without a base path. The two new behaviours:

../api-reference/operators/aggregation/%24limit.md -> /docs/reference/operators/aggregation/%24limit/
../../../api-reference/commands/query-and-write/find.md -> /docs/reference/commands/query-and-write/find/
[base=preview] functions.md -> /preview/docs/postgres-api/functions/
[base=preview] python-setup.md?view=full#connect -> /preview/docs/getting-started/python-setup/?view=full#connect
[base=preview] #examples -> #examples

[guanzhousongmicrosoft]

You are right, and my previous fix was wrong in a way its own tests could not detect. Corrected in 4ab8888.

The mechanism.Markdown is a client component, so markdownLinks ships in the browser bundle, and NEXT_BASE_PATH is not NEXT_PUBLIC_-prefixed — Next strips it from that bundle. Under a configured base path the static render, which runs in node where the variable exists, emitted /preview/docs/...; the same code after hydration emitted /docs/.... The href changed under the reader, with a hydration mismatch alongside it.

Two things made this easy to miss, and both are worth recording:

• The exported HTML is correct in the broken version. The export comes from the server-side render that reads the variable fine, so nothing on disk looks wrong. A build-level assertion would have passed — and would also pass on a future regression, which is why I did not add one.
• vitest runs in node, so my base-path tests exercised the one environment where the bug does not exist. They asserted the prefix was applied and were green.

I also cited Navbar as precedent for calling withBasePath from a client component. That was the wrong reasoning: it is the same latent defect, not a sanction. More on that below.

The fix. The resolver is pure again and returns a base-path-relative route. The anchor renderer uses next/link when the href was rewritten — which by definition makes it an internal document route — and next/link applies the basePath from next.config identically on the server and in the browser. Hrefs the resolver leaves alone still render as plain anchors, so external links, fragments and hand-written absolute paths behave exactly as before. No new environment variable, and nothing for a deployment to keep in sync.

Coverage, following the same reasoning rather than the original request:

• The base-path tests now assert the route is unchanged whether or not NEXT_BASE_PATH is set, including a case that compares both directly.
• A source guard asserts neither client-reachable module mentions NEXT_BASE_PATH, sitePath or withBasePath, with comments stripped first.

On "browser/build-level coverage" specifically: build-level cannot catch this, for the reason above. Browser-level would need hydration testing, and the project has no harness for it — jsdom and testing-library are not dependencies, and adding them is more than this branch should carry, especially as npm ci fails against the registry proxy on my machine so I could not validate the setup. The guard therefore sits at the source, where the mistake is actually made. If you would rather have the real thing, adding a hydration harness is worth its own PR.

Related, not fixed here.Navbar.tsx calls withBasePath at module scope in a client component — for the blogs anchor and the logo image — and has the same defect. It is a separate surface, so I left it alone rather than growing this branch. Happy to take it next.

Verified locally as far as the environment allows: the resolver returns identical routes with and without NEXT_BASE_PATH set, and both modules pass the source guard. The suite itself is left to CI.

[guanzhousongmicrosoft]

Reopened as #141 from a personal fork, so the branch and the pull request are owned by the same account that authors the commits. The tree is identical — the same three commits, unchanged.

The review discussion above stays here rather than moving: the api-reference mapping and NEXT_BASE_PATH findings and the correction on why the base path could not be read in the browser are both worth reading alongside #141, and #141's description summarizes both.

Closing in favour of #141.