fix/links: Fix broken heading links (25 mechanical drifts + 3 line-mates)

[marcleblanc2]

Linear FE-499: Fix doc site issues

Smaller, more easily reviewed subset of fixes from #1861

25 #anchor links whose target heading still exists with the same words, but the slug drifted:

• _ vs -
• doubled --
• a stray "
• punctuation github-slugger strips (ssl/https → sslhttps, merge/close → mergeclose, Sourcegraph's → sourcegraphs, kustomization.yaml → kustomizationyaml)

No page changes, no wording changes. Every new anchor matches a real heading on the target page, so review is a skim: the words on both sides of each → are the same.

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

Also carries 3 fixes from other buckets that share a line with a slug fix here, so the bucket PRs (#1865–#1872) never touch the same lines as this one:

• docs/self-hosted/http-https-configuration.mdx: /#quick-install → /self-hosted/deploy (home page lost that section)
• docs/batch-changes/site-admin-configuration.mdx: #commit-signing-for-github → #commit-signing-with-github-apps (heading reworded)
• docs/batch-changes/batch-spec-yaml-reference.mdx: #workspaces-examples → #examples-18 (heading reworded to plain "Examples"; the page has many, so github-slugger numbers them — fragile, but a unique heading would be a content change)

One to note: #deploy-sourcegraph → #deploy-sourcegraph- in docs/self-hosted/deploy/machine-images/aws-oneclick.mdx — the heading is ## Deploy Sourcegraph 🎉 and the slugger turns the emoji into a trailing -, so its slug has a trailing -. Fixing the heading instead would be cleaner but changes a URL; left as a slug fix here.

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 28 changed links against https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app: 28 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 28 links

File containing the link	Old link (broken today)	New link (preview)	Page rendered	Anchor found
docs/admin/auth/index.mdx	/admin/config/authorization-and-authentication#bitbucket-server-bitbucket-data-center-authorization	/admin/config/authorization-and-authentication#bitbucket-server--bitbucket-data-center-authorization	✅	✅
docs/admin/auth/saml/microsoft-adfs.mdx	/self-hosted/http-https-configuration#nginx-ssl-https-configuration	/self-hosted/http-https-configuration#nginx-sslhttps-configuration	✅	✅
docs/admin/code-hosts/non-git.mdx	#next-steps--advanced-configuration	#next-steps-advanced-configuration	✅	✅
docs/admin/search.mdx	/self-hosted/observability/alerts#zoekt-memory-map-areas-percentage-used	/self-hosted/observability/alerts#zoekt-memory_map_areas_percentage_used	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#changesettemplate-branch	#changesettemplatebranch	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#steps-run	#stepsrun	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#on-repository	#onrepository	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#changesettemplate-branch	#changesettemplatebranch	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#changesettemplate-branch	#changesettemplatebranch	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#changesettemplate-title	#changesettemplatetitle	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#changesettemplate-title	#changesettemplatetitle	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#workspaces-in	#workspacesin	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#changesettemplate-branch	#changesettemplatebranch	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#workspaces-examples	#examples-18	✅	✅
docs/batch-changes/batch-spec-yaml-reference.mdx	#steps-outputs	#stepsoutputs	✅	✅
docs/batch-changes/site-admin-configuration.mdx	/admin/config/batch-changes#automatically-delete-branches-on-merge-close	/admin/config/batch-changes#automatically-delete-branches-on-mergeclose	✅	✅
docs/batch-changes/site-admin-configuration.mdx	/admin/config/batch-changes#commit-signing-for-github	/admin/config/batch-changes#commit-signing-with-github-apps	✅	✅
docs/code-insights/explanations/current-limitations-of-code-insights.mdx	/admin/permissions/api#Setting-sub-repository-permissions-for-users	/admin/permissions/api#setting-sub-repository-permissions-for-users	✅	✅
docs/code-insights/references/requirements.mdx	/admin/permissions/api#Setting-sub-repository-permissions-for-users	/admin/permissions/api#setting-sub-repository-permissions-for-users	✅	✅
docs/code-navigation/auto-indexing-configuration.mdx	#index-jobs	#index_jobs	✅	✅
docs/self-hosted/deploy/kubernetes/troubleshoot.mdx	#symbols-sidebar-and-hovers-are-not-working"	#symbols-sidebar-and-hovers-are-not-working	✅	✅
docs/self-hosted/deploy/machine-images/aws-oneclick.mdx	#deploy-sourcegraph	#deploy-sourcegraph-	✅	✅
docs/self-hosted/faq.mdx	/self-hosted/observability/dashboards#frontend-provisioning-container-cpu-usage-long-term	/self-hosted/observability/dashboards#frontend-provisioning_container_cpu_usage_long_term	✅	✅
docs/self-hosted/faq.mdx	/self-hosted/observability/alerts#frontend-container-cpu-usage	/self-hosted/observability/alerts#frontend-container_cpu_usage	✅	✅
docs/self-hosted/faq.mdx	#can-i-consume-sourcegraph-s-metrics-in-my-own-monitoring-system-datadog-new-relic-etc	#can-i-consume-sourcegraphs-metrics-in-my-own-monitoring-system-datadog-new-relic-etc	✅	✅
docs/self-hosted/http-https-configuration.mdx	#nginx-ssl-https-configuration	#nginx-sslhttps-configuration	✅	✅
docs/self-hosted/http-https-configuration.mdx	#nginx-ssl-https-configuration	#nginx-sslhttps-configuration	✅	✅
docs/self-hosted/http-https-configuration.mdx	/#quick-install	/self-hosted/deploy	✅	—

Dropped from this PR: 11 same-page anchors in docs/self-hosted/deploy/kubernetes/kustomize/index.mdx. That file is shadowed by kustomize.mdx at the same route and never renders, so its links cannot be verified (or clicked) on the site. They go with the shadowed-route cleanup instead.

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 10, 2026 1:15am UTC