[BUG] Two outbound GitHub links 404 (blog backup-and-restore guide, Building from source)

[GuanzhouSong]

Two outbound GitHub links on the site return 404.

Revised. The original version claimed no replacement target existed upstream for the second link and that it "needs a maintainer decision rather than a mechanical fix." That was wrong — AGENTS.md and packaging/README.md both document builds. Corrected in §2.

1. Blog post: backup and restore guide

Root cause: the link is missing the operations/ path segment. The guide was filed under a subdirectory; the link points at the parent.

blogs/_posts/2026-03-19-meet-documentdb-kubernetes-operator.md:92:

- [Backup and restore guide](https://github.com/documentdb/documentdb-kubernetes-operator/blob/main/docs/operator-public-documentation/preview/backup-and-restore.md)

The preview/ directory contains 12 entries, and backup-and-restore.md is not among them:

advanced-configuration/ api-reference.md architecture/
configuration/ faq.md getting-started/
high-availability/ index.md kubectl-plugin.md
monitoring/ multi-region-deployment/ operations/

It lives one level deeper:

docs/operator-public-documentation/preview/operations/
 backup-and-restore.md failover.md maintenance.md
 restore-deleted-cluster.md upgrades.md

Fix: insert operations/ before the filename. Verified 200.

The post contains seven links to the operator repo (lines 86, 90, 91, 92, 93, 94, 95). Only line 92 is broken; the other six return 200.

2. "Building from source"

Root cause: the target was deleted upstream. docs/v1/building.md was removed — along with the entire docs/ tree — in documentdb/documentdb commit 77d6e0f6 ("Clean up stale docs and workflow actions (#551)", 2026-04-08), which retired the MkDocs site in favour of documentdb.io. The site link was never updated.

app/services/articleService.ts:277, in the "Next steps" list of the Linux Packages quick start (## Next steps at :274, content block :109-284, rendered at /docs/getting-started/packages):

- [Building from source](https://github.com/documentdb/documentdb/blob/main/docs/v1/building.md)

The repo has no docs/ directory at all:

$ curl -s https://api.github.com/repos/documentdb/documentdb/contents/docs
{ "message": "Not Found", "status": "404" }

Fix — replacement targets do exist:

• AGENTS.md has a literal ## Build section (line 40) with make, make install, make DEBUG=yes, plus a cargo make build block for the Rust gateway and a preceding ## Development Environment section covering the dev-container flow and full dependency set. Caveat: it is framed for AI coding agents, so it is not a drop-in equivalent of a user-facing building.md.
• packaging/README.md is titled "Building DocumentDB Packages With Docker" — the closer match for a packages quick start.
• Also available: scripts/build_documentdb_with_scripts.sh, scripts/build_and_install_with_pgrx.sh, scripts/build_and_start_gateway.sh.

Given this bullet sits in the Linux Packages guide, packaging/README.md is probably the right target. Dropping the bullet is also reasonable.

Reproduce

curl -s -o /dev/null -L -w "blog backup guide : %{http_code}\n" \
 https://github.com/documentdb/documentdb-kubernetes-operator/blob/main/docs/operator-public-documentation/preview/backup-and-restore.md
curl -s -o /dev/null -L -w "with operations/ : %{http_code}\n" \
 https://github.com/documentdb/documentdb-kubernetes-operator/blob/main/docs/operator-public-documentation/preview/operations/backup-and-restore.md
curl -s -o /dev/null -L -w "building.md : %{http_code}\n" \
 https://github.com/documentdb/documentdb/blob/main/docs/v1/building.md

blog backup guide : 404
with operations/ : 200
building.md : 404

Validation

All unique external URLs across app/, blogs/, and articles/ were status-checked with a browser user-agent. These two are the only genuine 404s.

Three hosts bot-block and return non-200 without being broken — they should be excluded from any automated link check rather than treated as failures: news.ycombinator.com, www.businesswire.com, and www.yugabyte.com (blogs/_data/posts.yml:47). Their exact status codes vary between runs (403/429/timeout), so a checker keying on status alone will flap.

[guanzhousongmicrosoft]

Both links fixed and verified live.

• Blog post backup-and-restore guide — fixed by Fix the Kubernetes operator links, install command, and missing content sync #135; the page now points at preview/operations/backup-and-restore.md, where the file moved to.
• Building from source on the packages quick start — fixed by Fix the outbound build-from-source link that 404s #132; now packaging/README.md, since docs/v1/building.md no longer exists upstream.