fix/links: Fix broken heading links (44 reworded, self-hosted)

[marcleblanc2]

Linear FE-499: Fix doc site issues

Smaller, more easily reviewed subset of fixes from #1861

#anchor links under docs/self-hosted/ whose target heading was reworded. The section still exists; the link now uses the current heading's slug.

Review: for each row, the new heading should be the same topic as the old anchor's words. Rows where the heading was replaced rather than renamed (e.g. several anchors collapsed onto one #configuration or #upgrade-types section) are the ones worth a second look.

Most rows are the Kustomize page: #buildconfig-yaml / #kustomization-yaml became one #step-3-set-up-the-configuration-files section (18 links), and the updates page: #standard-upgrades / #multi-version-upgrades → #upgrade-types, #update-policy → #release-schedule-and-versioning.

Checker findings (npm run check-links -- --check-anchors, from #1858, with its heading-slug fix): 278 on main → 234 on this branch.

Verification

The docs site serves its not-found page with HTTP 200 (fix in progress), so status codes prove nothing. Instead, every changed link was fetched on this PR's Vercel preview and the rendered HTML checked for two ids: the target page's own first heading (taken from its MDX source — the 404 page never has it) and the link's #fragment. Script: node dev/verify-links-live.mjs --site <preview-url>, coming in #1858.

Old links point at the current production site so you can see the breakage; new links point at the preview and land on the heading.

Checked 44 changed links against https://sourcegraph-docs-git-fix-reworded-a-15f39f-sourcegraph-f8c71130.vercel.app: 44 resolve, 0 fail.
Page rendered = the target page's first heading id is present (the 404 page never has it); Anchor = the #fragment is an id on the page. Old links point at the current site.

All 44 links

File containing the link	Old link (broken today)	New link (preview)	Page rendered	Anchor found
docs/self-hosted/deploy/docker-compose/operations.mdx	#restoring-sourcegraph-databases-into-an-existing-environment	#restore-sourcegraph-databases-into-an-existing-environment	✅	✅
docs/self-hosted/deploy/docker-compose/upgrade.mdx	/self-hosted/deploy/docker-compose/#step-1-prepare-the-deployment-repository	/self-hosted/deploy/docker-compose#step-1-fork-the-deployment-repository	✅	✅
docs/self-hosted/deploy/kubernetes/azure.mdx	/self-hosted/deploy/kubernetes/configure#configure-a-storage-class	/self-hosted/deploy/kubernetes/configure#storage-class	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomization-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomization-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomization-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomizationyaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomizationyaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/configure.mdx	/self-hosted/updates/#multi-version-upgrades	/self-hosted/updates#upgrade-types	✅	✅
docs/self-hosted/deploy/kubernetes/kustomize.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomization-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/kustomize.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/kustomize/eks.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/kustomize/gke.mdx	/self-hosted/deploy/kubernetes/kustomize#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/kustomize/migrate.mdx	/self-hosted/deploy/kubernetes/kustomize/#kustomization-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/kustomize/migrate.mdx	/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml	/self-hosted/deploy/kubernetes/kustomize#step-3-set-up-the-configuration-files	✅	✅
docs/self-hosted/deploy/kubernetes/operations.mdx	/self-hosted/deploy/kubernetes/#installation	/self-hosted/deploy/kubernetes#quickstart	✅	✅
docs/self-hosted/deploy/kubernetes/troubleshoot.mdx	/self-hosted/deploy/kubernetes/configure#security-configure-network-access	/self-hosted/deploy/kubernetes/configure#network-access	✅	✅
docs/self-hosted/deploy/machine-images/aws-ami.mdx	/self-hosted/updates#update-policy	/self-hosted/updates#release-schedule-and-versioning	✅	✅
docs/self-hosted/deploy/machine-images/gce.mdx	/self-hosted/updates#update-policy	/self-hosted/updates#release-schedule-and-versioning	✅	✅
docs/self-hosted/deploy/repositories.mdx	/self-hosted/updates#standard-upgrades	/self-hosted/updates#upgrade-types	✅	✅
docs/self-hosted/deploy/repositories.mdx	/self-hosted/updates#multi-version-upgrades	/self-hosted/updates#upgrade-types	✅	✅
docs/self-hosted/deploy/single-node/script.mdx	/self-hosted/updates#update-policy	/self-hosted/updates#release-schedule-and-versioning	✅	✅
docs/self-hosted/external-services/index.mdx	/self-hosted/observability/tracing#Use-an-external-Jaeger-instance	/self-hosted/observability/tracing#jaeger	✅	✅
docs/self-hosted/how-to/dirty-database.mdx	/self-hosted/updates/migrator/migrator-operations#kubernetes	/self-hosted/updates/migrator/migrator-operations#kubernetes-helm	✅	✅
docs/self-hosted/how-to/dirty-database.mdx	/self-hosted/updates/migrator/migrator-operations#docker--docker-compose	/self-hosted/updates/migrator/migrator-operations#docker-compose	✅	✅
docs/self-hosted/how-to/index.mdx	/self-hosted/updates/migrator/migrator-operations#upto	/self-hosted/updates/migrator/migrator-operations#upgrade	✅	✅
docs/self-hosted/how-to/index.mdx	/self-hosted/updates/migrator/migrator-operations#downto	/self-hosted/updates/migrator/migrator-operations#downgrade	✅	✅
docs/self-hosted/how-to/index.mdx	/self-hosted/updates/migrator/migrator-operations#kubernetes	/self-hosted/updates/migrator/migrator-operations#kubernetes-helm	✅	✅
docs/self-hosted/how-to/index.mdx	/self-hosted/updates/migrator/migrator-operations#docker--docker-compose	/self-hosted/updates/migrator/migrator-operations#docker-compose	✅	✅
docs/self-hosted/how-to/index.mdx	/admin/how-to/remove-repo#manually-purge-deleted-repository-data-from-disk	/admin/how-to/remove-repo#remove-corrupted-repository-data-from-sourcegraph	✅	✅
docs/self-hosted/how-to/unfinished-migration.mdx	/self-hosted/updates/#standard-upgrades	/self-hosted/updates#upgrade-types	✅	✅
docs/self-hosted/how-to/unfinished-migration.mdx	/self-hosted/updates/#multi-version-upgrades	/self-hosted/updates#upgrade-types	✅	✅
docs/self-hosted/observability/troubleshooting.mdx	/self-hosted/observability/metrics#accessing-prometheus	/self-hosted/observability/metrics#accessing-prometheus-directly	✅	✅
docs/self-hosted/observability/troubleshooting.mdx	/self-hosted/observability/tracing#accessing-jaeger	/self-hosted/observability/tracing#jaeger	✅	✅
docs/self-hosted/observability/troubleshooting.mdx	/self-hosted/observability/tracing#accessing-jaeger	/self-hosted/observability/tracing#jaeger	✅	✅
docs/self-hosted/updates/migrator/migrator-operations.mdx	#upto	#upgrade	✅	✅
docs/self-hosted/updates/migrator/upgrading-early-versions.mdx	/self-hosted/postgres#upgrading-internal-postgresql-instances	/self-hosted/postgres#upgrading-built-in-postgresql	✅	✅

Amp threads

• Docs - Fix broken heading links

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sourcegraph-docs	Ready	Preview	Sep 7, 2026 11:26pm UTC