Fix 19 documentation links that 404, and correct the touched pages against the engine source

[GuanzhouSong]

Fixesdocumentdb/documentdb.github.io#126.

19 rendered documentation links resolve to a 404. Four distinct causes, all confirmed against the live site. Verifying the affected pages against the DocumentDB engine and gateway sources also turned up a number of factual errors and unrunnable examples on those same pages — see Content corrections.

Cause 1 — bare sibling links resolve one level too deep (10 links)

documentdb.io serves pages with a trailing slash, so per RFC 3986 the base for a relative link is the directory.../find/, and a bare target becomes a child of the current page:

/docs/reference/commands/query-and-write/find/ + insert
-> /docs/reference/commands/query-and-write/find/insert (404)

No link rewriting happens for inline markdown links, so this is invisible to source review — it only reproduces against the exported URLs.

Affected: find.md (2), delete.md (2), update.md (2), insert.md (2), getMore.md (2).

Cause 2 — /docs/api-reference does not exist (3 links)

The reference is served at /docs/reference. Fixed in postgres-api/functions.md and getting-started/mongo-shell-quickstart.md (2).

The quickstart pair does not currently render — documentdb.io shadows that route with hardcoded content that already uses the correct path — so those two are latent rather than live. They go live the moment the override is removed, so they are fixed here too.

Cause 3 — .md extension leaks into rendered links (5 links)

Inline markdown links are not rewritten, so the extension reaches the browser verbatim:

• postgres-api/index.md — [Functions](functions.md) -> /docs/postgres-api/functions.md
• api-reference/operators/aggregation/$bucketauto.md (3) — [`$bucket`](./%24bucket.md) -> .../$bucketauto/%24bucket.md
• getting-started/python-setup.md:286 — [MongoDB Shell Guide](mongo-shell-quickstart.md) -> /docs/getting-started/python-setup/mongo-shell-quickstart.md

The $bucketauto and python-setup links compounded two bugs: leaked extension and wrong depth.

Note postgres-api/navigation.yml also uses link: functions.md, but that is correct and untouched — the nav pipeline strips the extension and renders href="/docs/postgres-api/functions/". Only the raw markdown renderer leaves it in.

Cause 4 — target no longer exists (1 link)

readme.md:8 linked to api-reference/index.md, which commit b6eb41a deleted when it made the api-reference landing pages generated. Repointed at the served location.

Why absolute URLs

Every corrected link uses an absolute https://documentdb.io/docs/... target rather than a site-relative one.

There is no relative form that works on both surfaces. Rendered on documentdb.io, find.md needs ../insert/; viewed as source on GitHub or in an editor, it needs insert.md. Picking either one breaks the other. Two of these links — postgres-api/index.md's functions.md and $bucketauto.md's ./%24bucket.md — currently work in source view, so a relative site-only fix would have traded a working link for a broken one:

200 https://github.com/documentdb/docs/blob/main/postgres-api/functions.md
404 https://github.com/documentdb/docs/blob/main/postgres-api/functions/

Absolute targets resolve on both, and match the form commit 2415b71 already used for this class of fix.

Every https://documentdb.io/docs/ link in the repository is normalized to carry a trailing slash, so it resolves directly instead of through a 301. Before this, 20 of 21 such links omitted it while the corrected ones carried it, leaving the same target spelled two ways — a later change to the URL base would have needed two patterns and silently missed half the links with either one.

Also removed

api-reference/operators/arithmetic-expression/index.md is deleted rather than having its Related Topics link repointed.

The file is never served — the folder URL returns the generated landing page, which contains none of this file's content, and /docs/reference/operators/arithmetic-expression/index/ 404s — so fixing the link inside it changes nothing. readme.md:20 states that api-reference landing pages are generated and index.md files are unnecessary, and this was the last straggler b6eb41a missed when it removed the other twenty. Its "More content to be added as operators are documented" line was stale besides: fifteen operators are documented in that folder. The landing-page description already lives in _metadata.description.md.

Content corrections

Validating the touched pages against the engine surfaced defects more severe than the links. Each is cited to the source that governs it.

Page	Problem
delete.md	deleteMany(filter, {"limit": 1}) was documented as the way to delete one of many matches. limit is a field of the wire-protocol deletes[] element, not a mongosh option, so it is ignored and every match is deleted (delete.c:889 takes the DeleteAllMatchingDocuments branch when limit is 0). Now uses deleteOne, with the wire-protocol form documented separately. Every example also filtered on discountPercentage: 21, a value absent from the sample document, so all of them returned deletedCount: 0 and the deleteOne/deleteMany distinction never demonstrated itself; switched to 19, which the sample matches three times. The duplicated "Example 3" heading is renumbered and the destructive deleteMany({}) moved last.
getMore.md	The cursor id must be a BSON int64 (bson_aggregation_pipeline.c:3101; the gateway requires as_i64() and rejects anything else with getMore value should be an i64), so both examples failed type validation before executing. Now wrapped in db.runCommand with NumberLong. An omitted batchSize does not fall back to a small default — aggregation_commands.c:2029 seeds INT_MAX, so the whole remaining cursor is returned, bounded by the 16 MB accumulated-batch cap (cursors.c:1059). The 101 default applies to the first page of find/aggregate only (system_configs.c:152). Adds maxTimeMS, and a warning that a short batch does not mean the cursor is drained.
insert.md	The ordered-insert example was not valid JavaScript — the options object's braces were missing. ordered already defaults to true (insert.c:294), which the parameter table did not say. The caption also claimed insertedIds confirms insertion order; it is keyed by input position and is identical under ordered: false.
$bucketauto.md	Both worked examples showed output the engine cannot produce. Recomputed from bson_bucket_auto.c: example 1 buckets to {3,18} {18,60} {60,230}, since a non-last bucket's max is the next bucket's first value (:780). Example 2 returns three buckets, not four — once a bucket's max is rounded up, following rows below it are absorbed (:732-755); the regression baseline shows the same collapse (bucket_auto.out:213-219 — 100 values, buckets:5, POWERSOF2 -> 3 rows). Behavior section expanded to cover the distribution rule, the shared boundaries, and the granularity rounding that causes the collapse.
mongo-shell-quickstart.md	createUser used role: "readWrite", db: "mydb"; users.c:1448-1471 accepts only readAnyDatabase, readWriteAnyDatabase, and clusterAdmin, and users.c:1479 requires db: "admin". createRole takes bare role names, not documents (roles.c:405-410), and must run against admin (roles.c:345, on by default). The index block created {email: 1} twice, colliding on the generated name email_1 so the unique index was silently never created (create_indexes.c:4512-4551). The vector index declared dimensions: 384 while the search example queried the same path with a 3-element vector. Adds the documentdb.enableRoleCrud prerequisite with the ALTER SYSTEM form, since it cannot be set from mongosh.
postgres-api/index.md	PLAIN/EntraId authentication is rejected by the gateway: auth.rs:357 accepts only SCRAM-SHA-256 and MONGODB-OIDC, and ismaster.rs:69 advertises only SCRAM-SHA-256. MONGODB-OIDC is not a usable substitute either — it calls documentdb_api_internal.authenticate_token (query_catalog.rs:593), which no SQL in the extensions defines. getting-started/index.md:48 carried the same claim in different words and is corrected too.
postgres-api/functions.md	Rebased onto #58, which rewrote this page against v0.114-0 and supersedes this branch's edits — including on one point where #58 is right and this branch was wrong (create_indexes_background does not wait for builds to finish; the SQL COMMENT ON says it does, the C implementation does not). Three corrections are restored on top: the /docs/api-reference link, which #58 reintroduced by branching from before this fix; update_role, still described as working when its body is a bare ereport(ERROR) (roles.c:190-195); and the absence of any mention of documentdb.enableRoleCrud (off by default) or enableRolesAdminDBCheck (on by default).
postgres-api/configuration.md	Gains both role flags, which the two pages above now refer to. They are not filed under the existing off-by-default table, whose preamble scopes it to flags that fail silently — these raise — so they get their own subsection.

Verification

Every documentdb.io link in the repository was extracted and status-checked. No 404s remain, and all 16 resolve directly with no redirect. The remaining external links were checked too; the only non-200 under HEAD is the VS Marketplace URL, which rejects HEAD and returns 200 to GET.

The only relative inline links left in the repository are the four in readme.md, which is a GitHub-rendered file (confirmed not served at /docs/) and whose targets all exist.

The original 14 links were found by crawling all 268 URLs in documentdb.io's sitemap.xml, extracting every rendered in-site href, resolving each against its containing page, and status-checking: 302 unique targets, 15 broken. The 15th is an operator docs URL fixed separately in documentdb/documentdb.github.io#131. The five added since came from reviewing the touched pages directly — python-setup.md:286 and the readme.md entry point were both missed by the crawl, the former because the earlier manual sweep stopped at the line above it.

Suggested follow-up

A link-check step in CI over the exported site would catch causes 1–3. Source-grepping catches none of cause 1, and would also report the shadowed quickstart links as broken when they do not currently render. Checking source-view resolution as well would catch the case that motivated absolute URLs here.

[GuanzhouSong]

Two findings of the same class as this PR, in files the diff does not touch — so they can't be left as inline comments.

I re-derived your model against the live site before reviewing, and it holds: /docs/X 301s to /docs/X/, /docs/api-reference 404s while /docs/reference 200s, and inline destinations really are emitted raw — curl https://documentdb.io/docs/postgres-api/ returns href="functions.md" verbatim while the nav entry beside it is rewritten to href="/docs/postgres-api/functions/". All 15 of the new targets return 200. The three causes are real and the fixes work.

1. getting-started/python-setup.md:286 — a live 404 of the same class, left unfixed

- Check out the [MongoDB Shell Guide](mongo-shell-quickstart.md) for additional query examples

This hits both causes at once: bare sibling depth and leaked .md. Confirmed:

404 https://documentdb.io/docs/getting-started/python-setup/mongo-shell-quickstart.md
200 https://documentdb.io/docs/getting-started/mongo-shell-quickstart/

After this PR it is the only remaining inline .md link in the published tree, so the "all links of this class" framing doesn't quite hold yet. Fix is ../mongo-shell-quickstart/ (or the absolute form).

Two things make it worth calling out beyond the single link. It points at mongo-shell-quickstart.md, a file this PR edits, so the pair was already in scope. And it survived the previous manual sweep too: git show 2415b71 -- getting-started/python-setup.md ("Fix broken website links (#39)") converted line 285 immediately above it and carried 286 through the hunk untouched. Two hand sweeps, adjacent lines, same miss — which is the strongest argument for the link-check CI your PR description already proposes. Worth landing that step in this PR rather than as follow-up; the repo has no .github/ directory at all today, so nothing re-validates these 18 hand-computed paths after merge.

2. readme.md:8 — dangling link to a file deleted 8 commits ago

-[API Reference](api-reference/index.md) - Detailed API documentation

api-reference/index.md does not exist (ls api-reference/ -> _metadata.description.md, commands/, operators/ only); it was removed in b6eb41a "Rework API reference folders (#4)". https://github.com/documentdb/docs/blob/main/api-reference/index.md -> 404. The other four entry points on lines 7, 9, 10, 11 all resolve.

It is self-contradicting too: line 20 of the same file explains why it's gone — "There's no need to add index.md files or manually maintain lists of reference articles." readme.md isn't served on the docs site, so GitHub is its only audience, and it's the first file a contributor opens. Suggested target is the absolute https://documentdb.io/docs/reference, already used five times elsewhere in the repo.

---

Separately, the counts in the commit don't reconcile: the title says "14 documentation links", the body says "Every one of the 15 links was verified", and the diff changes 18 destinations (delete 2, find 2, getMore 2, insert 2, update 2, $bucketauto 3, arithmetic index 1, quickstart 2, functions.md 1, postgres-api/index.md 1). The body's own sub-counts sum to 18. Worth aligning so a future bisector can tell nothing was changed unintentionally.