From b7f5bd351672b118363ed1ede0ae26184fc565cc Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:13:33 -0600
Subject: [PATCH 01/14] ci: fail PRs that break redirects, with suggested fixes

dev/check-redirects.mjs checks every entry in src/data/redirects.ts:
source shadows a page, source has a #fragment, duplicate source,
/docs prefix, chained redirect, missing destination page or heading.
The workflow compares against the merge base, so only redirects a PR
breaks are reported, grouped by problem with the fix explained under
each heading, and posts one suggested change per fixable entry the PR
added (deleted again once the finding is gone).

Not part of `npm run check`: main has hundreds of pre-existing
findings.

Squash of the check-redirects branch rebased onto main; the check-links
commits it carried are already on main.

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 .github/workflows/check-redirects.yml | 133 +++++++
 AGENTS.md                             |   1 +
 dev/check-redirects.mjs               | 492 ++++++++++++++++++++++++++
 3 files changed, 626 insertions(+)
 create mode 100644 .github/workflows/check-redirects.yml
 create mode 100644 dev/check-redirects.mjs

diff --git a/.github/workflows/check-redirects.yml b/.github/workflows/check-redirects.yml
new file mode 100644
index 000000000..634678aa0
--- /dev/null
+++ b/.github/workflows/check-redirects.yml
@@ -0,0 +1,133 @@
+name: Check redirects
+
+# Reports redirects in src/data/redirects.ts that this PR breaks, compared with
+# the merge base: destinations that no longer exist, #fragments whose heading
+# was renamed, and new redirects that shadow an existing page. Pre-existing
+# broken redirects on the base branch are ignored.
+
+on:
+    pull_request:
+
+# A new push supersedes the run for the previous one
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+    pull-requests: write
+
+jobs:
+    check-redirects:
+        name: Broken redirects introduced by this PR
+        runs-on: ubuntu-latest
+        steps:
+            - name: Check out pull request head
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha }}
+                  fetch-depth: 0
+
+            - name: Install github-slugger, the only dependency of dev/check-redirects.mjs
+              # Into a scratch prefix, not the repo: `npm install <pkg>` next to
+              # package.json would install every dependency of the site
+              run: |
+                  npm install --prefix "$RUNNER_TEMP/deps" --no-package-lock --no-audit --no-fund \
+                      "github-slugger@$(node -p 'require("./package.json").dependencies["github-slugger"]')"
+                  ln -s "$RUNNER_TEMP/deps/node_modules" node_modules
+
+            - name: Check out merge base
+              env:
+                  BASE_SHA: ${{ github.event.pull_request.base.sha }}
+              run: |
+                  merge_base=$(git merge-base "$BASE_SHA" HEAD)
+                  git worktree add "$RUNNER_TEMP/base" "$merge_base"
+                  git diff -U0 "$merge_base" HEAD -- src/data/redirects.ts > "$RUNNER_TEMP/changes.diff"
+
+            - name: Record broken redirects already present on the base branch
+              # Exit 1 means findings, which is expected here
+              run: |
+                  node dev/check-redirects.mjs --format json \
+                      --root "$RUNNER_TEMP/base" > "$RUNNER_TEMP/base-redirects.json" \
+                      || [ $? -eq 1 ]
+
+            - name: Find redirects broken by this PR
+              id: check
+              env:
+                  # Line links in the report open redirects.ts on the PR branch
+                  LINK_BASE: ${{ github.event.pull_request.head.repo.html_url }}/blob/${{ github.event.pull_request.head.ref }}
+              run: |
+                  if node dev/check-redirects.mjs --format markdown \
+                      --baseline "$RUNNER_TEMP/base-redirects.json" \
+                      --diff "$RUNNER_TEMP/changes.diff" \
+                      --review "$RUNNER_TEMP/review.json" \
+                      --link-base "$LINK_BASE" > "$RUNNER_TEMP/report.md"; then
+                      echo "broken=false" >> "$GITHUB_OUTPUT"
+                  else
+                      echo "broken=true" >> "$GITHUB_OUTPUT"
+                  fi
+                  cat "$RUNNER_TEMP/report.md"
+
+            - name: Comment on the pull request
+              # Fork PRs get a read-only token; the report is still in the job log
+              if: github.event.pull_request.head.repo.full_name == github.repository
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  PR_NUMBER: ${{ github.event.pull_request.number }}
+                  BROKEN: ${{ steps.check.outputs.broken }}
+              run: |
+                  marker='<!-- check-redirects-report -->'
+                  existing_comment=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" \
+                      --paginate --jq ".[] | select(.body | startswith(\"$marker\")) | .id" | head -n 1)
+
+                  # Comment only when there is something to report, or an earlier report to resolve
+                  if [ "$BROKEN" = true ]; then
+                      { echo "$marker"; cat "$RUNNER_TEMP/report.md"; } > "$RUNNER_TEMP/comment.md"
+                  elif [ -n "$existing_comment" ]; then
+                      printf '%s\n### ✅ The redirects an earlier revision of this PR broke are fixed\n' \
+                          "$marker" > "$RUNNER_TEMP/comment.md"
+                  else
+                      exit 0
+                  fi
+
+                  if [ -n "$existing_comment" ]; then
+                      gh api --method PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$existing_comment" \
+                          --field body=@"$RUNNER_TEMP/comment.md"
+                  else
+                      gh pr comment "$PR_NUMBER" --body-file "$RUNNER_TEMP/comment.md"
+                  fi
+
+            - name: Suggest fixes as review comments
+              # One suggested change per fixable entry this PR added. Suggestions
+              # already on the PR (same lines and entry) are not posted again;
+              # suggestions for findings that are gone are deleted. GitHub sets line
+              # to null on comments it could not carry to the new revision, so those
+              # are deleted too.
+              if: github.event.pull_request.head.repo.full_name == github.repository
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  PR_NUMBER: ${{ github.event.pull_request.number }}
+              run: |
+                  key='(.path + ":" + (.line | tostring) + ":" + (.body | split("\n")[0]))'
+                  gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" --paginate \
+                      --jq ".[] | select(.body | startswith(\"<!-- check-redirects-finding:\")) | {id, key: $key}" \
+                      | jq -s . > "$RUNNER_TEMP/posted.json"
+                  jq --slurpfile posted "$RUNNER_TEMP/posted.json" \
+                      ".comments |= map(select($key as \$key | \$posted[0] | any(.key == \$key) | not))" \
+                      "$RUNNER_TEMP/review.json" > "$RUNNER_TEMP/review-new.json"
+
+                  jq -r --slurpfile review "$RUNNER_TEMP/review.json" \
+                      ".[] | select(.key as \$key | \$review[0].comments | any($key == \$key) | not) | .id" \
+                      "$RUNNER_TEMP/posted.json" | while read -r comment_id; do
+                      gh api --method DELETE "repos/$GITHUB_REPOSITORY/pulls/comments/$comment_id"
+                  done
+
+                  if [ "$(jq '.comments | length' "$RUNNER_TEMP/review-new.json")" -gt 0 ]; then
+                      gh api --method POST "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
+                          --input "$RUNNER_TEMP/review-new.json" > /dev/null \
+                          || echo "::warning::Could not post the suggested fixes; they are in the report above"
+                  fi
+
+            - name: Fail when this PR breaks redirects
+              if: steps.check.outputs.broken == 'true'
+              run: exit 1
diff --git a/AGENTS.md b/AGENTS.md
index 580711718..ee04f0472 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,6 +8,7 @@
 -   **Lint**: `npm run lint`
 -   **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames, images); `npm run build` runs them first, so any finding fails a deploy
 -   **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links; see `dev/check-links.mjs`; the build runs it without flags, so only dead page links fail a deploy). When moving a page or renaming a heading, update every link to it; a redirect in `src/data/redirects.ts` does not satisfy the check. Link to this site with relative paths (`/admin/config/site-config`), never `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`. To also probe the external links you added: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)`
+-   **Check redirects**: `node dev/check-redirects.mjs` reports broken entries in `src/data/redirects.ts` (CI comments on PRs that break redirects; see the script header for what it checks). Not part of `npm run check`: main has hundreds of pre-existing findings, and CI only reports the ones a PR adds
 -   **Prove changed links resolve on a deploy**: `node dev/verify-links-live.mjs --site <vercel-preview-url>` prints a Markdown table for the PR description
 
 ## AI Chat Integration
diff --git a/dev/check-redirects.mjs b/dev/check-redirects.mjs
new file mode 100644
index 000000000..6317eacc8
--- /dev/null
+++ b/dev/check-redirects.mjs
@@ -0,0 +1,492 @@
+#!/usr/bin/env node
+
+/**
+ * Checks redirects in src/data/redirects.ts.
+ *
+ * Redirects exist so external traffic to an old URL still reaches a page, so
+ * each one must be correct. Checks, for every entry:
+ * - the source does not shadow an existing page (the middleware would redirect
+ *   visitors away from a page that exists)
+ * - the source has no #fragment: browsers never send fragments, so such an
+ *   entry can never match
+ * - the source has no earlier entry: the middleware uses the first match only
+ * - neither path starts with /docs: the middleware strips that prefix from
+ *   requests and adds it to destinations
+ * - the destination is a page, not another redirect
+ * - the destination page exists under docs/ (or is a file under public/)
+ * - when the destination has a #fragment, the heading exists on that page
+ *
+ * External (http) destinations are not checked.
+ *
+ * Usage: node dev/check-redirects.mjs [options]
+ *   --root <dir>           Repository to check (default: this repository)
+ *   --format <name>        Output as text (default), json, or markdown
+ *   --baseline <file>      Only report findings absent from this JSON file
+ *                          (produced by --format json on another revision)
+ *   --link-base <url>      Markdown output links each line to
+ *                          <url>/src/data/redirects.ts, e.g.
+ *                          https://github.com/sourcegraph/docs/blob/<branch>
+ *   --diff <file>          `git diff` output; with --review, only entries this
+ *                          diff added get a suggested change
+ *   --review <file>        Write a pull request review with one suggested
+ *                          change per fixable finding to this JSON file
+ *
+ * Exits 1 when any finding is reported.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import vm from 'vm';
+import {fileURLToPath} from 'url';
+import {extractHeadings, listFiles, routeFor} from './check-links.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+const ROOT_DIR = path.resolve(flagValue('--root') ?? path.dirname(__dirname));
+const FORMAT = flagValue('--format') ?? 'text';
+const BASELINE_FILE = flagValue('--baseline');
+const LINK_BASE = flagValue('--link-base')?.replace(/\/$/, '');
+const DIFF_FILE = flagValue('--diff');
+const REVIEW_FILE = flagValue('--review');
+
+const REDIRECTS_PATH = 'src/data/redirects.ts';
+const REDIRECTS_FILE = path.join(ROOT_DIR, REDIRECTS_PATH);
+const CONSTANTS_FILE = path.join(ROOT_DIR, 'src/data/constants.ts');
+const DOCS_DIR = path.join(ROOT_DIR, 'docs');
+const PUBLIC_DIR = path.join(ROOT_DIR, 'public');
+// Report sections, most urgent first: a shadowed page is unreachable today.
+// `fix` teaches the author what a correct entry looks like, where it applies.
+const PROBLEM = {
+	shadowsPage: {
+		heading: 'Source overshadows a docs page that exists',
+		fix:
+			"Redirects take precedence over pages, so visitors to that page's URL are redirected away from it. " +
+			'Update or remove the redirect or the page to remove the conflict.'
+	},
+	fragmentSource: {
+		heading: 'Source has a #fragment, so this redirect can never match',
+		fix:
+			'Use the page path alone as the source. #fragments are processed in the browser, so browsers ' +
+			'never send them to web servers.\n\n' +
+			'If the redirect destination has a #fragment, it takes precedence, otherwise if the customer ' +
+			"clicked a link which has a #fragment, it'll be kept and tried on the destination page."
+	},
+	docsPrefix: {
+		heading: 'Source or destination starts with /docs',
+		fix:
+			'Write paths without the /docs prefix. The site removes /docs from the requested URL before ' +
+			'matching sources, and adds it back in front of the destination, so a /docs/... source never ' +
+			'matches and a /docs/... destination lands on /docs/docs/....'
+	},
+	duplicateSource: {
+		heading:
+			'Source already has an earlier entry, so this one is never used',
+		fix: 'Only the first entry for a source matches. Update that entry instead of adding another.'
+	},
+	chained: {
+		heading: 'Destination is another redirect',
+		fix:
+			"Chained redirects cost the customer's browser a round trip, slow down their page load time, " +
+			'and frustrate them. They also make the redirects file impossible to maintain, and make it too ' +
+			"easy to create redirect loops. Change the rule's destination to the final destination."
+	},
+	missingPage: {
+		heading: 'Destination page does not exist',
+		fix:
+			'Set the redirect destination to the page that replaced it, or remove the rule if there is no replacement page; ' +
+			"visitors then get our fancy 404 page, with links they can click to find where they're trying " +
+			'to go, and the search bar.'
+	},
+	missingHeading: {
+		heading: 'Destination heading does not exist',
+		fix: "Use the heading's correct anchor, or drop the #fragment to land the customer at the top of the page."
+	}
+};
+
+function flagValue(name) {
+	const index = args.indexOf(name);
+	return index === -1 ? undefined : args[index + 1];
+}
+
+// Load redirects.ts without a TypeScript toolchain. The file is plain data
+// plus one import, so strip the module syntax and evaluate it.
+// Returns [{ source, destination, line }].
+function loadRedirects() {
+	const source = fs.readFileSync(REDIRECTS_FILE, 'utf-8');
+	const constants = fs.readFileSync(CONSTANTS_FILE, 'utf-8');
+	const rssUrl =
+		constants.match(
+			/TECHNICAL_CHANGELOG_RSS_URL\s*=\s*['"]([^'"]+)['"]/
+		)?.[1] ?? '';
+
+	const script = source
+		.replace(/^import .*$/gm, '')
+		.replace(/^export const /gm, 'const ')
+		.replace(/module\.exports\s*=\s*\{[\s\S]*?\};?/g, '');
+
+	const sandbox = {TECHNICAL_CHANGELOG_RSS_URL: rssUrl};
+	vm.runInNewContext(`${script}\nresult = updatedRedirectsData;`, sandbox);
+
+	// Line numbers of each entry, for the report and suggested changes: the
+	// `source:` line, plus the `{` and `}` lines around it. Entries are written
+	// one `source:` per line; if that assumption fails, omit line numbers.
+	const lines = source.split('\n');
+	const arrayEnd = lines.findIndex(line => /^\];?\s*$/.test(line));
+	const positions = [];
+	lines.slice(0, arrayEnd).forEach((line, index) => {
+		if (!/^\s*source:/.test(line)) return;
+		let start = index;
+		while (start > 0 && !/^\s*\{\s*$/.test(lines[start])) start--;
+		let end = index;
+		while (end < arrayEnd && !/^\s*\},?\s*$/.test(lines[end])) end++;
+		positions.push({line: index + 1, startLine: start + 1, endLine: end + 1});
+	});
+	const havePositions = positions.length === sandbox.result.length;
+
+	return sandbox.result.map((redirect, index) => ({
+		source: redirect.source,
+		destination: redirect.destination,
+		...(havePositions ? positions[index] : {})
+	}));
+}
+
+// Site route -> Set of anchors on that page. When foo.mdx and foo/index.mdx
+// both exist the first (sorted) file owns the route, as in check-links.mjs.
+function buildHeadingsByRoute() {
+	const headingsByRoute = new Map();
+	for (const file of listFiles(DOCS_DIR, ['.mdx'])) {
+		const route = routeFor(file);
+		if (headingsByRoute.has(route)) continue;
+		headingsByRoute.set(
+			route,
+			extractHeadings(fs.readFileSync(path.join(DOCS_DIR, file), 'utf-8'))
+		);
+	}
+	return headingsByRoute;
+}
+
+// '/foo/bar/?x=1#baz' -> { pathname: '/foo/bar', fragment: 'baz' }
+function splitUrl(url) {
+	const [pathAndQuery, fragment = ''] = url.split('#');
+	const pathname = pathAndQuery.split('?')[0].replace(/\/+$/, '') || '/';
+	return {pathname, fragment: decodeURIComponent(fragment)};
+}
+
+function isPublicFile(pathname) {
+	const fullPath = path.join(PUBLIC_DIR, pathname);
+	return fullPath.startsWith(PUBLIC_DIR) && fs.existsSync(fullPath);
+}
+
+function isExternal(url) {
+	return /^https?:\/\//.test(url);
+}
+
+// Every incorrect redirect: [{ source, destination, line, problem, detail?, fix? }].
+// `fix` is the entry that should replace this one, or {remove: true}, where the
+// fix is mechanical; a shadowed page or missing destination needs a human.
+function findBrokenRedirects(redirects, headingsByRoute) {
+	const findings = [];
+	const firstBySource = new Map();
+	for (const redirect of redirects) {
+		if (!firstBySource.has(redirect.source))
+			firstBySource.set(redirect.source, redirect);
+	}
+	const report = (redirect, problem, {detail, fix} = {}) =>
+		findings.push({...redirect, problem: problem.heading, detail, fix});
+	const withoutFragment = url => url.split('#')[0];
+	const withoutDocsPrefix = url => url.replace(/^\/docs(?=\/)/, '');
+	const isRedirect = pathname =>
+		firstBySource.has(pathname) && !headingsByRoute.has(pathname);
+
+	for (const redirect of redirects) {
+		const source = splitUrl(redirect.source);
+		if (source.fragment) {
+			// Another entry may already cover the source without its fragment
+			const fix = firstBySource.has(withoutFragment(redirect.source))
+				? {remove: true}
+				: {source: withoutFragment(redirect.source), destination: redirect.destination};
+			report(redirect, PROBLEM.fragmentSource, {fix});
+			continue;
+		}
+		if (firstBySource.get(redirect.source) !== redirect) {
+			report(redirect, PROBLEM.duplicateSource, {fix: {remove: true}});
+			continue;
+		}
+		if (headingsByRoute.has(source.pathname)) {
+			report(redirect, PROBLEM.shadowsPage);
+		}
+		if (
+			source.pathname.startsWith('/docs/') ||
+			redirect.destination.startsWith('/docs/')
+		) {
+			report(redirect, PROBLEM.docsPrefix, {
+				fix: {
+					source: withoutDocsPrefix(redirect.source),
+					destination: withoutDocsPrefix(redirect.destination)
+				}
+			});
+			continue;
+		}
+		if (isExternal(redirect.destination)) continue;
+
+		const destination = splitUrl(redirect.destination);
+		if (isRedirect(destination.pathname)) {
+			const final = finalDestination(destination.pathname);
+			report(redirect, PROBLEM.chained, {
+				detail: final ?? 'none, redirect loop',
+				fix: final && {source: redirect.source, destination: final}
+			});
+			continue;
+		}
+		const headings = headingsByRoute.get(destination.pathname);
+		if (!headings) {
+			if (!isPublicFile(destination.pathname)) {
+				report(redirect, PROBLEM.missingPage);
+			}
+			continue;
+		}
+		if (destination.fragment && !headings.has(destination.fragment)) {
+			report(redirect, PROBLEM.missingHeading, {
+				fix: {source: redirect.source, destination: destination.pathname}
+			});
+		}
+	}
+
+	// Where a visitor to `pathname` finally lands; undefined for a redirect loop
+	function finalDestination(pathname) {
+		const visited = new Set();
+		while (isRedirect(pathname) && !visited.has(pathname)) {
+			visited.add(pathname);
+			pathname = firstBySource.get(pathname).destination;
+			if (isExternal(pathname)) return pathname;
+			pathname = splitUrl(pathname).pathname;
+		}
+		return visited.has(pathname) ? undefined : pathname;
+	}
+	return findings;
+}
+
+// Line numbers are left out so an entry that only moved is not a new finding
+function findingKey(finding) {
+	return `${finding.source}\u0000${finding.destination}\u0000${finding.problem}`;
+}
+
+function withoutBaseline(findings, baselineFile) {
+	const baseline = new Set(
+		JSON.parse(fs.readFileSync(baselineFile, 'utf-8')).map(findingKey)
+	);
+	return findings.filter(finding => !baseline.has(findingKey(finding)));
+}
+
+// 'remove this entry', or which of source and destination to change to what
+function describeFix({source, destination, fix}) {
+	if (fix.remove) return 'remove this entry';
+	const changes = [
+		...(fix.source !== source ? [`the source to \`${fix.source}\``] : []),
+		...(fix.destination !== destination
+			? [`the destination to \`${fix.destination}\``]
+			: [])
+	];
+	return `change ${changes.join(' and ')}`;
+}
+
+function formatText(findings) {
+	const scope = BASELINE_FILE ? 'broken by this change' : 'broken';
+	if (findings.length === 0) {
+		return `✅ No redirects ${scope}\n`;
+	}
+	const lines = [`❌ ${findings.length} redirect(s) ${scope}:`, ''];
+	for (const finding of findings) {
+		const {source, destination, line, problem, detail, fix} = finding;
+		lines.push(
+			`  ${REDIRECTS_PATH}${line ? `:${line}` : ''}`,
+			`    ${source} -> ${destination}`,
+			`    ${problem}${detail ? ` (final destination: ${detail})` : ''}`,
+			...(fix ? [`    Fix: ${describeFix(finding).replaceAll('`', '')}`] : []),
+			''
+		);
+	}
+	return lines.join('\n');
+}
+
+function linkTo(text, url) {
+	return url ? `[${text}](${url})` : text;
+}
+
+// Map of problem heading -> its findings in line order, sections in PROBLEM order
+function groupByProblem(findings) {
+	const groups = new Map(
+		Object.values(PROBLEM).map(({heading}) => [heading, []])
+	);
+	for (const finding of findings) groups.get(finding.problem).push(finding);
+	for (const [problem, entries] of groups) {
+		if (entries.length === 0) groups.delete(problem);
+		else entries.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+	}
+	return groups;
+}
+
+// Body for a pull request comment
+function formatMarkdown(findings) {
+	if (findings.length === 0) {
+		return '### ✅ This PR breaks no redirects\n';
+	}
+
+	// ?plain=1 opens GitHub's code view, where #L<n> anchors work
+	const fileUrl = LINK_BASE && `${LINK_BASE}/${REDIRECTS_PATH}?plain=1`;
+	const lines = [
+		`### ❌ This PR breaks ${findings.length} redirect(s)`,
+		'',
+		'Redirects are used so inbound traffic from external sources (links inside old versions of ' +
+			'our product, bookmarks, search results, etc.) to old doc pages still reaches a relevant page.',
+		'',
+		'A correct entry maps the old page path, exactly as the browser requests it, ' +
+			'straight to a page that exists today, with an optional #heading that exists on the destination page:',
+		'',
+		'```ts',
+		'{',
+		"\tsource: '/old/section/page',",
+		"\tdestination: '/new/section/page#heading-slug'",
+		'},',
+		'```',
+		'',
+		'Each section below explains how to fix the entries listed under it.',
+		'',
+		'Do not use redirects for broken internal links, internal links must be fixed ' +
+			'properly to tame the tech debt snowball no one wants to deal with; the ' +
+			'"Check links" PR check comment lists the links this PR broke, if any.',
+		'',
+		linkTo(`**\`${REDIRECTS_PATH}\`**`, fileUrl)
+	];
+	// One section per problem with its fix. Each entry is shown as it appears
+	// in the redirects file, so it is easy to find there.
+	const fixes = new Map(
+		Object.values(PROBLEM).map(({heading, fix}) => [heading, fix])
+	);
+	for (const [problem, entries] of groupByProblem(findings)) {
+		lines.push('', `#### ${problem}`, '', fixes.get(problem), '');
+		for (const finding of entries) {
+			const {source, destination, line, detail, fix} = finding;
+			const where = line
+				? linkTo(`line ${line}`, fileUrl && `${fileUrl}#L${line}`)
+				: 'entry';
+			lines.push(
+				`- ${where}`,
+				'  ```ts',
+				`  source: '${source}',`,
+				`  destination: '${destination}'`,
+				...(detail ? [`  final destination: ${detail}`] : []),
+				'  ```',
+				...(fix ? [`  Fix: ${describeFix(finding)}`] : [])
+			);
+		}
+	}
+	lines.push(
+		'',
+		'Reproduce locally with `node dev/check-redirects.mjs`'
+	);
+	return lines.join('\n') + '\n';
+}
+
+// Line numbers `git diff` output added to redirects.ts
+function addedLines(diffFile) {
+	const added = new Set();
+	let inRedirects = false;
+	let lineNumber;
+	for (const line of fs.readFileSync(diffFile, 'utf-8').split('\n')) {
+		if (line.startsWith('+++ ')) {
+			inRedirects = line === `+++ b/${REDIRECTS_PATH}`;
+		} else if (line.startsWith('@@ ')) {
+			lineNumber = Number(line.match(/^@@ -\S+ \+(\d+)/)[1]);
+		} else if (inRedirects && line.startsWith('+')) {
+			added.add(lineNumber++);
+		} else if (inRedirects && line.startsWith(' ')) {
+			lineNumber++;
+		}
+	}
+	return added;
+}
+
+// First line of a review comment, so the workflow can match the comments it
+// posted earlier to the findings still present and delete the rest
+const REVIEW_MARKER = '<!-- check-redirects-finding:';
+
+// Body for POST /repos/{owner}/{repo}/pulls/{n}/reviews: one suggested change
+// per fixable finding whose entry this PR added, replacing the whole entry
+// (or deleting it). Review comments must sit on lines of the diff, hence the
+// added-lines restriction. No review body: a submitted review cannot be
+// deleted, so a body would outlive the comments once the entries are fixed.
+function reviewRequest(findings, added) {
+	const sourceLines = fs.readFileSync(REDIRECTS_FILE, 'utf-8').split('\n');
+	const lineNumbers = (start, end) =>
+		Array.from({length: end - start + 1}, (_, offset) => start + offset);
+	const comments = findings
+		.filter(
+			({fix, startLine, endLine}) =>
+				fix && startLine && lineNumbers(startLine, endLine).every(line => added.has(line))
+		)
+		.map(finding => {
+			const {source, destination, problem, fix, startLine, endLine} = finding;
+			const indent = sourceLines[startLine - 1].match(/^\s*/)[0];
+			const comma = sourceLines[endLine - 1].trimEnd().endsWith(',') ? ',' : '';
+			const entry = fix.remove
+				? []
+				: [
+						`${indent}{`,
+						`${indent}\tsource: '${fix.source}',`,
+						`${indent}\tdestination: '${fix.destination}'`,
+						`${indent}}${comma}`
+					];
+			const body = [
+				`${REVIEW_MARKER} ${source} -> ${destination} -->`,
+				`Problem: ${problem}`,
+				`Fix: ${describeFix(finding)}`,
+				'````suggestion',
+				...entry,
+				'````'
+			];
+			return {
+				path: REDIRECTS_PATH,
+				...(startLine !== endLine && {start_line: startLine, start_side: 'RIGHT'}),
+				line: endLine,
+				side: 'RIGHT',
+				body: body.join('\n')
+			};
+		});
+	return {event: 'COMMENT', body: '', comments};
+}
+
+const FORMATTERS = {
+	text: formatText,
+	json: findings => JSON.stringify(findings, null, '\t') + '\n',
+	markdown: formatMarkdown
+};
+
+function main() {
+	const format = FORMATTERS[FORMAT];
+	if (!format) {
+		throw new Error(
+			`Unknown --format "${FORMAT}"; use text, json, or markdown`
+		);
+	}
+
+	let findings = findBrokenRedirects(loadRedirects(), buildHeadingsByRoute());
+	if (BASELINE_FILE) {
+		findings = withoutBaseline(findings, BASELINE_FILE);
+	}
+
+	if (REVIEW_FILE) {
+		const added = DIFF_FILE ? addedLines(DIFF_FILE) : new Set();
+		fs.writeFileSync(
+			REVIEW_FILE,
+			JSON.stringify(reviewRequest(findings, added), null, '\t') + '\n'
+		);
+	}
+
+	// Not process.exit(): that can truncate stdout when it is a pipe
+	process.stdout.write(format(findings));
+	process.exitCode = findings.length === 0 ? 0 : 1;
+}
+
+main();

From b2f29c2576034b177e379bf719291a8a40aeda9b Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:26:15 -0600
Subject: [PATCH 02/14] check-redirects: don't repeat the final destination the
 Fix line already names

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 dev/check-redirects.mjs | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/dev/check-redirects.mjs b/dev/check-redirects.mjs
index 6317eacc8..f13831db8 100644
--- a/dev/check-redirects.mjs
+++ b/dev/check-redirects.mjs
@@ -232,11 +232,15 @@ function findBrokenRedirects(redirects, headingsByRoute) {
 
 		const destination = splitUrl(redirect.destination);
 		if (isRedirect(destination.pathname)) {
+			// The fix names the final destination; only a loop needs `detail`
 			const final = finalDestination(destination.pathname);
-			report(redirect, PROBLEM.chained, {
-				detail: final ?? 'none, redirect loop',
-				fix: final && {source: redirect.source, destination: final}
-			});
+			report(
+				redirect,
+				PROBLEM.chained,
+				final
+					? {fix: {source: redirect.source, destination: final}}
+					: {detail: 'none, redirect loop'}
+			);
 			continue;
 		}
 		const headings = headingsByRoute.get(destination.pathname);

From 1508206a48760cac8b0bc328908459e03d0b75a3 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 09:06:08 -0600
Subject: [PATCH 03/14] check-redirects: sync review comments with
 dev/sync-review-comments.sh (from the check-links PR)

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 .github/workflows/check-redirects.yml | 28 +++------------------------
 1 file changed, 3 insertions(+), 25 deletions(-)

diff --git a/.github/workflows/check-redirects.yml b/.github/workflows/check-redirects.yml
index 634678aa0..706bd254e 100644
--- a/.github/workflows/check-redirects.yml
+++ b/.github/workflows/check-redirects.yml
@@ -98,35 +98,13 @@ jobs:
                   fi
 
             - name: Suggest fixes as review comments
-              # One suggested change per fixable entry this PR added. Suggestions
-              # already on the PR (same lines and entry) are not posted again;
-              # suggestions for findings that are gone are deleted. GitHub sets line
-              # to null on comments it could not carry to the new revision, so those
-              # are deleted too.
+              # One suggested change per fixable entry this PR added, kept in sync
+              # with the findings; see dev/sync-review-comments.sh
               if: github.event.pull_request.head.repo.full_name == github.repository
               env:
                   GH_TOKEN: ${{ github.token }}
                   PR_NUMBER: ${{ github.event.pull_request.number }}
-              run: |
-                  key='(.path + ":" + (.line | tostring) + ":" + (.body | split("\n")[0]))'
-                  gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" --paginate \
-                      --jq ".[] | select(.body | startswith(\"<!-- check-redirects-finding:\")) | {id, key: $key}" \
-                      | jq -s . > "$RUNNER_TEMP/posted.json"
-                  jq --slurpfile posted "$RUNNER_TEMP/posted.json" \
-                      ".comments |= map(select($key as \$key | \$posted[0] | any(.key == \$key) | not))" \
-                      "$RUNNER_TEMP/review.json" > "$RUNNER_TEMP/review-new.json"
-
-                  jq -r --slurpfile review "$RUNNER_TEMP/review.json" \
-                      ".[] | select(.key as \$key | \$review[0].comments | any($key == \$key) | not) | .id" \
-                      "$RUNNER_TEMP/posted.json" | while read -r comment_id; do
-                      gh api --method DELETE "repos/$GITHUB_REPOSITORY/pulls/comments/$comment_id"
-                  done
-
-                  if [ "$(jq '.comments | length' "$RUNNER_TEMP/review-new.json")" -gt 0 ]; then
-                      gh api --method POST "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
-                          --input "$RUNNER_TEMP/review-new.json" > /dev/null \
-                          || echo "::warning::Could not post the suggested fixes; they are in the report above"
-                  fi
+              run: dev/sync-review-comments.sh '<!-- check-redirects-finding:' "$RUNNER_TEMP/review.json"
 
             - name: Fail when this PR breaks redirects
               if: steps.check.outputs.broken == 'true'

From 80527ae328c97c6c606285a4e867f57b00825ce1 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 04:54:05 -0600
Subject: [PATCH 04/14] check-links: one suggestion per fix, synced with
 findings; report one fact per line

- Review comments: one suggested change per finding with a fix, no review
  body. Each starts with a marker so the workflow can delete suggestions
  for findings that are fixed and skip ones already posted.
- Summary comment and review comments list line, link, problem, and fix
  on their own lines.
- Absolute links to this site get their own section instead of Outbound.
- Case-mismatch findings now carry a fix.
- Wording: 'links on this site', 'these other pages', drop
  docs.sourcegraph.com; reproduce command matches package.json.

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 .github/workflows/check-links.yml |  20 +++--
 dev/check-links.mjs               | 137 ++++++++++++++----------------
 2 files changed, 81 insertions(+), 76 deletions(-)

diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml
index e0dab4ba3..98063e9d6 100644
--- a/.github/workflows/check-links.yml
+++ b/.github/workflows/check-links.yml
@@ -97,19 +97,29 @@ jobs:
                   fi
 
             - name: Suggest fixes as review comments
-              # One suggested change per added line with a fix. Suggestions already on
-              # the PR (same file, line, and text) are not posted again.
-              if: steps.check.outputs.broken == 'true' && github.event.pull_request.head.repo.full_name == github.repository
+              # One suggested change per finding with a fix. Suggestions already on the
+              # PR (same file, line, and link) are not posted again; suggestions for
+              # findings that are gone are deleted. GitHub sets line to null on comments
+              # it could not carry to the new revision, so those are deleted too.
+              if: github.event.pull_request.head.repo.full_name == github.repository
               env:
                   GH_TOKEN: ${{ github.token }}
                   PR_NUMBER: ${{ github.event.pull_request.number }}
               run: |
+                  key='(.path + ":" + (.line | tostring) + ":" + (.body | split("\n")[0]))'
                   gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" --paginate \
-                      --jq '.[] | {path, line, body}' | jq -s . > "$RUNNER_TEMP/posted.json"
+                      --jq ".[] | select(.body | startswith(\"<!-- check-links-finding:\")) | {id, key: $key}" \
+                      | jq -s . > "$RUNNER_TEMP/posted.json"
                   jq --slurpfile posted "$RUNNER_TEMP/posted.json" \
-                      '.comments |= map(select(. as $comment | $posted[0] | index({path: $comment.path, line: $comment.line, body: $comment.body}) | not))' \
+                      ".comments |= map(select($key as \$key | \$posted[0] | any(.key == \$key) | not))" \
                       "$RUNNER_TEMP/review.json" > "$RUNNER_TEMP/review-new.json"
 
+                  jq -r --slurpfile review "$RUNNER_TEMP/review.json" \
+                      ".[] | select(.key as \$key | \$review[0].comments | any($key == \$key) | not) | .id" \
+                      "$RUNNER_TEMP/posted.json" | while read -r comment_id; do
+                      gh api --method DELETE "repos/$GITHUB_REPOSITORY/pulls/comments/$comment_id"
+                  done
+
                   if [ "$(jq '.comments | length' "$RUNNER_TEMP/review-new.json")" -gt 0 ]; then
                       gh api --method POST "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
                           --input "$RUNNER_TEMP/review-new.json" > /dev/null \
diff --git a/dev/check-links.mjs b/dev/check-links.mjs
index e37c940f7..5eab267b9 100644
--- a/dev/check-links.mjs
+++ b/dev/check-links.mjs
@@ -307,15 +307,16 @@ function validateSelfLink(url, currentFile, maps) {
 	const visited = new Set();
 	let candidate = relative;
 	while (true) {
-		const moved = candidate === relative ? '' : ' to a moved page';
+		const error = candidate === relative ? 'Absolute link to this site' : 'Absolute link to a moved page';
 		const problem = validateLink({ url: candidate }, currentFile, maps);
 		if (!problem) {
-			return { error: `Absolute self-link${moved}; use "${candidate}" instead`, fix: candidate };
+			return { error, fix: candidate };
 		}
 		const destination = maps.redirects.get(candidate.split('#')[0]);
 		if (!destination || visited.has(destination)) {
-			const replaced = moved ? `; "${candidate}" replaced it, but` : ', and';
-			return { error: `Absolute self-link${moved}${replaced} ${problem[0].toLowerCase()}${problem.slice(1)}` };
+			const message = problem.error ?? problem;
+			const replaced = candidate === relative ? ', and' : `; "${candidate}" replaced it, but`;
+			return { error: `${error}${replaced} ${message[0].toLowerCase()}${message.slice(1)}` };
 		}
 		visited.add(destination);
 		candidate = isSelfLink(destination) ? relativeSelfLink(destination) : destination;
@@ -413,7 +414,7 @@ function validateLink(link, currentFile, maps) {
 		resolvedPath.replace(/\/$/, '').toLowerCase()
 	);
 	if (realPath) {
-		return `Case mismatch: "${resolvedPath}" should be "${realPath}"`;
+		return { error: `Case mismatch: "${resolvedPath}" should be "${realPath}"`, fix: anchor ? `${realPath}#${anchor}` : realPath };
 	}
 	
 	// Check if it's a file with extension (like .png, .pdf)
@@ -543,9 +544,9 @@ function formatText(findings) {
 	];
 	for (const [file, fileFindings] of byFile) {
 		lines.push(`\n📄 ${file}`);
-		for (const { line, url, error } of fileFindings) {
+		for (const { line, url, error, fix } of fileFindings) {
 			lines.push(`   Line ${line}: ${url}`);
-			lines.push(`   └─ ${error}`);
+			lines.push(`   └─ ${error}${fix ? `; use ${fix}` : ''}`);
 		}
 	}
 	return lines.join('\n') + '\n';
@@ -555,7 +556,8 @@ function linkTo(text, url) {
 	return url ? `[${text}](${url})` : text;
 }
 
-// Markdown list of findings grouped by file, linked to the source when --link-base is set
+// Markdown list of findings grouped by file, one line per fact, linked to the
+// source when --link-base is set
 function markdownFindingList(findings) {
 	const lines = [];
 	for (const [file, fileFindings] of groupByFile(findings)) {
@@ -563,59 +565,58 @@ function markdownFindingList(findings) {
 		// Markdown preview ignores them
 		const fileUrl = LINK_BASE && `${LINK_BASE}/${file}?plain=1`;
 		lines.push(linkTo(`**\`${file}\`**`, fileUrl));
-		for (const { line, url, error } of fileFindings) {
-			lines.push(`- ${linkTo(`line ${line}`, fileUrl && `${fileUrl}#L${line}`)}: \`${url}\` — ${error}`);
+		for (const { line, url, error, fix } of fileFindings) {
+			lines.push(
+				`- ${linkTo(`line ${line}`, fileUrl && `${fileUrl}#L${line}`)}`,
+				`  - Link: \`${url}\``,
+				`  - Problem: ${error}`,
+				...(fix ? [`  - Fix: \`${fix}\``] : [])
+			);
 		}
 		lines.push('');
 	}
 	return lines;
 }
 
+const ABSOLUTE_LINKS_ADVICE =
+	'Write links on this site as relative paths (`/admin/config/site-config`), ' +
+	'not `https://sourcegraph.com/docs/…`: absolute links leave the preview ' +
+	'deployment and local dev server, and hide moved pages behind redirects.';
+
 // Body for a pull request comment. With --diff, findings are split into
-// outbound (in a file this PR changed: the PR added or edited a bad link) and
-// inbound (in a file it did not: the PR renamed or removed a link target).
+// outbound (in a file this PR changed: the PR added or edited a bad link),
+// absolute links to this site, and inbound (in a file the PR did not change:
+// the PR renamed or removed a link target).
 function formatMarkdown(findings) {
 	if (findings.length === 0) {
 		return '### ✅ This PR introduces no broken links\n';
 	}
 	
 	const lines = [`### ❌ This PR introduces ${findings.length} broken link(s)`, ''];
-	if (DIFF) {
-		const outbound = findings.filter(finding => DIFF.files.has(finding.file));
-		const inbound = findings.filter(finding => !DIFF.files.has(finding.file));
-		if (outbound.length > 0) {
-			lines.push(
-				'### Outbound',
-				'',
-				'Your PR includes links to pages or anchors that do not exist, or absolute links to this site.',
-				'',
-				...markdownFindingList(outbound)
-			);
-		}
-		if (inbound.length > 0) {
-			lines.push(
-				'### Inbound',
-				'',
-				'A change your PR made broke inbound links from elsewhere. ' +
-					'Please fix the inbound links on the other pages.',
-				'',
-				...markdownFindingList(inbound)
-			);
+	const section = (heading, intro, sectionFindings) => {
+		if (sectionFindings.length > 0) {
+			lines.push(`### ${heading}`, '', intro, '', ...markdownFindingList(sectionFindings));
 		}
+	};
+	if (DIFF) {
+		const absolute = findings.filter(finding => isSelfLink(finding.url));
+		const outbound = findings.filter(finding => !isSelfLink(finding.url) && DIFF.files.has(finding.file));
+		const inbound = findings.filter(finding => !isSelfLink(finding.url) && !DIFF.files.has(finding.file));
+		section('Outbound', 'Your PR includes links to pages or anchors that do not exist.', outbound);
+		section('Absolute links', ABSOLUTE_LINKS_ADVICE, absolute);
+		section(
+			'Inbound',
+			'A change your PR made broke inbound links from elsewhere. Please fix the inbound links on these other pages.',
+			inbound
+		);
 	} else {
 		lines.push(...markdownFindingList(findings));
-	}
-	if (findings.some(finding => isSelfLink(finding.url))) {
-		lines.push(
-			'Write links to this site as relative paths (`/admin/config/site-config`), ' +
-				'not `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`: ' +
-				'absolute links leave the preview deployment and local dev server, and ' +
-				'hide moved pages behind redirects.',
-			''
-		);
+		if (findings.some(finding => isSelfLink(finding.url))) {
+			lines.push(ABSOLUTE_LINKS_ADVICE, '');
+		}
 	}
 	lines.push(
-		'Reproduce locally with `pnpm check-links --check-anchors` ' +
+		'Reproduce locally with `pnpm check links --check-anchors --check-self-links` ' +
 			'(see `dev/check-links.mjs`).',
 		'',
 		'Adding a redirect in `src/data/redirects.ts` does not satisfy this ' +
@@ -624,38 +625,32 @@ function formatMarkdown(findings) {
 	return lines.join('\n') + '\n';
 }
 
+// First line of a review comment, so the workflow can match the comments it
+// posted earlier to the findings still present and delete the rest
+const REVIEW_MARKER = '<!-- check-links-finding:';
+
 // Body for POST /repos/{owner}/{repo}/pulls/{n}/reviews: one suggested change per
-// added line that has fixes, so the author can apply them from the PR. The comment
-// lists every finding on the line, so the ones the suggestion cannot fix are not
-// mistaken for accepted. Review comments must sit on a line of the diff, hence the
-// added-line restriction.
+// finding that has a fix, so the author can apply each from the PR. Review comments
+// must sit on a line of the diff, hence the added-line restriction. No review body:
+// a submitted review cannot be deleted, so a body would outlive the comments once
+// the links are fixed.
 function reviewRequest(findings) {
-	const findingsByLine = new Map();
-	for (const finding of findings) {
-		if (!isAddedLine(finding.file, finding.line)) continue;
-		const key = `${finding.file}:${finding.line}`;
-		if (!findingsByLine.has(key)) findingsByLine.set(key, []);
-		findingsByLine.get(key).push(finding);
-	}
-
-	const comments = [...findingsByLine.values()]
-		.filter(lineFindings => lineFindings.some(finding => finding.fix))
-		.map(lineFindings => {
-			const { file, line } = lineFindings[0];
+	const comments = findings
+		.filter(({ file, line, fix }) => fix && isAddedLine(file, line))
+		.map(({ file, line, url, error, fix }) => {
 			const source = fs.readFileSync(path.join(ROOT_DIR, file), 'utf-8').split('\n')[line - 1];
-			const fixed = lineFindings
-				.filter(finding => finding.fix)
-				.reduce((text, { url, fix }) => text.split(url).join(fix), source);
-			const notes = lineFindings.map(
-				({ url, error, fix }) => `- \`${url}\`: ${error}${fix ? '' : ' (not fixed by this suggestion)'}`
-			);
-			return { path: file, line, side: 'RIGHT', body: [...notes, '```suggestion', fixed, '```'].join('\n') };
+			const body = [
+				`${REVIEW_MARKER} ${url} -->`,
+				`Link: \`${url}\``,
+				`Problem: ${error}`,
+				`Fix: \`${fix}\``,
+				'````suggestion',
+				source.split(url).join(fix),
+				'````'
+			];
+			return { path: file, line, side: 'RIGHT', body: body.join('\n') };
 		});
-	return {
-		event: 'COMMENT',
-		body: 'Suggested fixes for the links this PR adds; details in the check-links comment.',
-		comments
-	};
+	return { event: 'COMMENT', body: '', comments };
 }
 
 const FORMATTERS = {

From e2f24a2390e93d74b297d48b92d3db63df1ffbe2 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:07:03 -0600
Subject: [PATCH 05/14] cspell: allow tostring, a jq builtin used in the
 workflows

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 cspell-allow-list.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index 9b26c3c7c..3411345cc 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -545,6 +545,7 @@ toolcall
 topk
 topsecretorg
 topsecretproject
+tostring # jq builtin
 transactionally
 transformchanges
 transformchangesgroup

From f92288605a4b78de0b6315b79ed35c173e3676f6 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:27:35 -0600
Subject: [PATCH 06/14] check-links: don't repeat the link and fix inside the
 case-mismatch problem

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 dev/check-links.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dev/check-links.mjs b/dev/check-links.mjs
index 5eab267b9..8ad57213f 100644
--- a/dev/check-links.mjs
+++ b/dev/check-links.mjs
@@ -414,7 +414,7 @@ function validateLink(link, currentFile, maps) {
 		resolvedPath.replace(/\/$/, '').toLowerCase()
 	);
 	if (realPath) {
-		return { error: `Case mismatch: "${resolvedPath}" should be "${realPath}"`, fix: anchor ? `${realPath}#${anchor}` : realPath };
+		return { error: 'Path case mismatch: works on macOS, 404s on the Linux build', fix: anchor ? `${realPath}#${anchor}` : realPath };
 	}
 	
 	// Check if it's a file with extension (like .png, .pdf)

From 41aae0f7383aff44608b7113456b2ab0efbcfdfd Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:32:30 -0600
Subject: [PATCH 07/14] check-links: inbound section wording

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 dev/check-links.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dev/check-links.mjs b/dev/check-links.mjs
index 8ad57213f..3bb48936e 100644
--- a/dev/check-links.mjs
+++ b/dev/check-links.mjs
@@ -606,7 +606,7 @@ function formatMarkdown(findings) {
 		section('Absolute links', ABSOLUTE_LINKS_ADVICE, absolute);
 		section(
 			'Inbound',
-			'A change your PR made broke inbound links from elsewhere. Please fix the inbound links on these other pages.',
+			'A change your PR made broke inbound links from these other files. Please fix the inbound links in these other files.',
 			inbound
 		);
 	} else {

From 2407a719dc650b6f319925e8d6edce2187f51be5 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 09:05:38 -0600
Subject: [PATCH 08/14] check-links: move review-comment sync to
 dev/sync-review-comments.sh; update comments whose text changed

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 .github/workflows/check-links.yml | 27 +++------------------
 dev/sync-review-comments.sh       | 40 +++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 24 deletions(-)
 create mode 100755 dev/sync-review-comments.sh

diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml
index 98063e9d6..c5e4d7503 100644
--- a/.github/workflows/check-links.yml
+++ b/.github/workflows/check-links.yml
@@ -97,34 +97,13 @@ jobs:
                   fi
 
             - name: Suggest fixes as review comments
-              # One suggested change per finding with a fix. Suggestions already on the
-              # PR (same file, line, and link) are not posted again; suggestions for
-              # findings that are gone are deleted. GitHub sets line to null on comments
-              # it could not carry to the new revision, so those are deleted too.
+              # One suggested change per finding with a fix, kept in sync with the
+              # findings; see dev/sync-review-comments.sh
               if: github.event.pull_request.head.repo.full_name == github.repository
               env:
                   GH_TOKEN: ${{ github.token }}
                   PR_NUMBER: ${{ github.event.pull_request.number }}
-              run: |
-                  key='(.path + ":" + (.line | tostring) + ":" + (.body | split("\n")[0]))'
-                  gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" --paginate \
-                      --jq ".[] | select(.body | startswith(\"<!-- check-links-finding:\")) | {id, key: $key}" \
-                      | jq -s . > "$RUNNER_TEMP/posted.json"
-                  jq --slurpfile posted "$RUNNER_TEMP/posted.json" \
-                      ".comments |= map(select($key as \$key | \$posted[0] | any(.key == \$key) | not))" \
-                      "$RUNNER_TEMP/review.json" > "$RUNNER_TEMP/review-new.json"
-
-                  jq -r --slurpfile review "$RUNNER_TEMP/review.json" \
-                      ".[] | select(.key as \$key | \$review[0].comments | any($key == \$key) | not) | .id" \
-                      "$RUNNER_TEMP/posted.json" | while read -r comment_id; do
-                      gh api --method DELETE "repos/$GITHUB_REPOSITORY/pulls/comments/$comment_id"
-                  done
-
-                  if [ "$(jq '.comments | length' "$RUNNER_TEMP/review-new.json")" -gt 0 ]; then
-                      gh api --method POST "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
-                          --input "$RUNNER_TEMP/review-new.json" > /dev/null \
-                          || echo "::warning::Could not post the suggested fixes; they are in the report above"
-                  fi
+              run: dev/sync-review-comments.sh '<!-- check-links-finding:' "$RUNNER_TEMP/review.json"
 
             - name: Fail when this PR introduces broken links
               if: steps.check.outputs.broken == 'true'
diff --git a/dev/sync-review-comments.sh b/dev/sync-review-comments.sh
new file mode 100755
index 000000000..6ecd7b806
--- /dev/null
+++ b/dev/sync-review-comments.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+# Make a check's suggested-change review comments on a PR match a review.json
+# ({comments: [{path, line, start_line?, body}]}): post the new ones, update
+# the ones whose text changed, and delete the ones whose finding is gone.
+# GitHub sets line to null on comments it could not carry to the new revision,
+# so those are deleted too. Comments are matched by file, line, and the
+# marker comment on their first line, e.g. "<!-- check-links-finding: <url> -->".
+#
+# Usage: dev/sync-review-comments.sh '<!-- check-links-finding:' review.json
+# Needs GH_TOKEN, GITHUB_REPOSITORY, and PR_NUMBER.
+set -eu
+marker=$1
+review=$2
+key='(.path + ":" + (.line | tostring) + ":" + (.body | split("\n")[0]))'
+pulls="repos/$GITHUB_REPOSITORY/pulls"
+
+posted=$(gh api "$pulls/$PR_NUMBER/comments" --paginate \
+    --jq ".[] | select(.body | startswith(\"$marker\")) | {id, body, key: $key}" | jq -s .)
+
+printf '%s' "$posted" | jq -c --slurpfile review "$review" ".[]
+    | .key as \$key
+    | (\$review[0].comments | map(select($key == \$key)) | first) as \$wanted
+    | if \$wanted == null then {id, method: \"DELETE\"}
+      elif \$wanted.body != .body then {id, method: \"PATCH\", body: \$wanted.body}
+      else empty end" \
+| while read -r change; do
+    comment="$pulls/comments/$(printf '%s' "$change" | jq -r .id)"
+    if [ "$(printf '%s' "$change" | jq -r .method)" = DELETE ]; then
+        gh api --method DELETE "$comment" < /dev/null
+    else
+        printf '%s' "$change" | jq '{body}' | gh api --method PATCH "$comment" --input - > /dev/null
+    fi
+done
+
+fresh=$(jq --argjson posted "$posted" \
+    ".comments |= map(select($key as \$key | \$posted | any(.key == \$key) | not))" "$review")
+if [ "$(printf '%s' "$fresh" | jq '.comments | length')" -gt 0 ]; then
+    printf '%s' "$fresh" | gh api --method POST "$pulls/$PR_NUMBER/reviews" --input - > /dev/null \
+        || echo "::warning::Could not post the suggested fixes; they are in the report above"
+fi

From 9bc08963f86fa3b91c743797d04a063752e34446 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 09:11:54 -0600
Subject: [PATCH 09/14] cspell: allow argjson, a jq option used in
 dev/sync-review-comments.sh

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
---
 cspell-allow-list.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index 3411345cc..4df15e327 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -40,6 +40,7 @@ appendonly
 appengine
 appgw
 ARGF
+argjson # jq option
 atoburl
 atoi
 attnum

From e9fe828169205d062321960b11d07fcd62ad8bc5 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 09:07:02 -0600
Subject: [PATCH 10/14] spell check: update inline comments whose text changed
 instead of leaving the old wording

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 dev/post-spelling-review.mjs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/dev/post-spelling-review.mjs b/dev/post-spelling-review.mjs
index 94eacb399..ef41020d5 100644
--- a/dev/post-spelling-review.mjs
+++ b/dev/post-spelling-review.mjs
@@ -258,6 +258,14 @@ async function syncInlineComments(findings) {
 			continue;
 		}
 		if (wanted.has(key)) {
+			const body = inlineBody(wanted.get(key));
+			if (body !== comment.body) {
+				await githubWrite(
+					'PATCH',
+					`/repos/${REPOSITORY}/pulls/comments/${comment.id}`,
+					{body}
+				);
+			}
 			wanted.delete(key);
 		} else {
 			await githubWrite(

From 37049f762b7285e92badbe021afabf149902a27f Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:05:07 -0600
Subject: [PATCH 11/14] ci: Comment the Vercel build log on PRs whose build
 fails

Vercel shows build logs only to members of its team, so contributors
saw a red X and a login wall. On vercel.deployment.error this posts the
tail of the build log on the PR; on the next successful build the same
comment is updated to say the failure is fixed. Fork PRs are skipped so
the project-scoped Vercel token is never used on their behalf.
---
 .github/workflows/vercel-build-report.yml |  52 ++++++
 AGENTS.md                                 |   1 +
 dev/report-vercel-build.mjs               | 198 ++++++++++++++++++++++
 3 files changed, 251 insertions(+)
 create mode 100644 .github/workflows/vercel-build-report.yml
 create mode 100644 dev/report-vercel-build.mjs

diff --git a/.github/workflows/vercel-build-report.yml b/.github/workflows/vercel-build-report.yml
new file mode 100644
index 000000000..576e3476b
--- /dev/null
+++ b/.github/workflows/vercel-build-report.yml
@@ -0,0 +1,52 @@
+name: Vercel build report
+
+# Vercel only shows build logs to members of its team. When a PR's Vercel
+# build fails, this comments the end of the build log on the PR; when a later
+# revision builds, the comment is updated to say so.
+#
+# GitHub only delivers repository_dispatch to the workflow file on the default
+# branch, so workflow_dispatch takes the same payload fields as inputs for
+# testing before merge and for re-running on a PR by hand:
+#   gh workflow run vercel-build-report.yml --ref <branch> \
+#       -f id=dpl_... -f state=error -f sha=<pr head sha>
+on:
+    repository_dispatch:
+        types: [vercel.deployment.error, vercel.deployment.success]
+    workflow_dispatch:
+        inputs:
+            id:
+                description: Vercel deployment ID (client_payload.id)
+                required: true
+            state:
+                description: Deployment state (client_payload.state.type)
+                required: true
+                type: choice
+                options: [error, success]
+            sha:
+                description: Full commit SHA of the PR head (client_payload.git.sha)
+                required: true
+
+permissions:
+    contents: read
+    pull-requests: write
+
+jobs:
+    report:
+        if: github.event.client_payload.environment != 'production'
+        runs-on: ubuntu-latest
+        steps:
+            - name: Check out dev/report-vercel-build.mjs
+              uses: actions/checkout@v4
+              with:
+                  sparse-checkout: dev/report-vercel-build.mjs
+                  sparse-checkout-cone-mode: false
+
+            - name: Comment on the pull request
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  DEPLOYMENT_ID: ${{ github.event.client_payload.id || inputs.id }}
+                  DEPLOYMENT_STATE: ${{ github.event.client_payload.state.type || inputs.state }}
+                  COMMIT_SHA: ${{ github.event.client_payload.git.sha || inputs.sha }}
+                  # Scoped to the sourcegraph-docs project, so it needs no team ID
+                  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+              run: node dev/report-vercel-build.mjs
diff --git a/AGENTS.md b/AGENTS.md
index ee04f0472..daeb0d343 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,7 @@
 -   **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links; see `dev/check-links.mjs`; the build runs it without flags, so only dead page links fail a deploy). When moving a page or renaming a heading, update every link to it; a redirect in `src/data/redirects.ts` does not satisfy the check. Link to this site with relative paths (`/admin/config/site-config`), never `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`. To also probe the external links you added: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)`
 -   **Check redirects**: `node dev/check-redirects.mjs` reports broken entries in `src/data/redirects.ts` (CI comments on PRs that break redirects; see the script header for what it checks). Not part of `npm run check`: main has hundreds of pre-existing findings, and CI only reports the ones a PR adds
 -   **Prove changed links resolve on a deploy**: `node dev/verify-links-live.mjs --site <vercel-preview-url>` prints a Markdown table for the PR description
+-   **Vercel build failures**: Vercel shows build logs only to its team members, so `.github/workflows/vercel-build-report.yml` comments the log tail on the PR (see `dev/report-vercel-build.mjs`). It reads Vercel with the `VERCEL_TOKEN` repo secret, a token scoped to the `sourcegraph-docs` project that expires 2026-12-10; mint a new one with `POST /v3/user/tokens?teamId=<team>` and `projectId` in the body
 
 ## AI Chat Integration
 
diff --git a/dev/report-vercel-build.mjs b/dev/report-vercel-build.mjs
new file mode 100644
index 000000000..3f9f16f10
--- /dev/null
+++ b/dev/report-vercel-build.mjs
@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+/**
+ * Reports a failed Vercel build on its pull request, since Vercel only shows
+ * build logs to members of the Vercel team. When a later revision builds, the
+ * same comment is updated to say so.
+ *
+ * Usage: node dev/report-vercel-build.mjs [--dry-run]
+ *
+ * Requires DEPLOYMENT_ID, DEPLOYMENT_STATE (error or success), COMMIT_SHA,
+ * GH_TOKEN and GITHUB_REPOSITORY. A failed build also needs VERCEL_TOKEN, and
+ * VERCEL_TEAM_ID unless the token is scoped to the project.
+ * With --dry-run the comment is printed instead of posted.
+ */
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const MAX_LOG_LINES = 100;
+const MAX_LOG_CHARS = 30_000;
+
+const API_URL = process.env.GITHUB_API_URL ?? 'https://api.github.com';
+const REPOSITORY = process.env.GITHUB_REPOSITORY;
+const {DEPLOYMENT_ID, DEPLOYMENT_STATE, COMMIT_SHA} = process.env;
+
+const MARKER = '<!-- vercel-build-report -->';
+
+async function fetchJson(url, headers) {
+	const response = await fetch(url, {headers});
+	if (!response.ok) {
+		throw new Error(
+			`GET ${url} failed: ${response.status} ${await response.text()}`
+		);
+	}
+	return response.json();
+}
+
+async function github(method, route, body) {
+	const response = await fetch(`${API_URL}${route}`, {
+		method,
+		headers: {
+			authorization: `Bearer ${process.env.GH_TOKEN}`,
+			accept: 'application/vnd.github+json',
+			'x-github-api-version': '2022-11-28',
+			...(body && {'content-type': 'application/json'})
+		},
+		body: body && JSON.stringify(body)
+	});
+	if (!response.ok) {
+		throw new Error(
+			`${method} ${route} failed: ${response.status} ${await response.text()}`
+		);
+	}
+	return response.json();
+}
+
+async function githubList(route) {
+	const items = [];
+	for (let page = 1; ; page++) {
+		const batch = await github('GET', `${route}?per_page=100&page=${page}`);
+		items.push(...batch);
+		if (batch.length < 100) {
+			return items;
+		}
+	}
+}
+
+// The dispatch payload has no PR number; look it up from the commit. A stale
+// event for a commit the PR has moved past is ignored. Fork PRs are ignored
+// too, so the Vercel token is only ever used for commits by people who can
+// already push to this repository.
+async function findPullRequest() {
+	const pulls = await github(
+		'GET',
+		`/repos/${REPOSITORY}/commits/${COMMIT_SHA}/pulls`
+	);
+	const pull = pulls.find(
+		pull => pull.state === 'open' && pull.head.sha === COMMIT_SHA
+	);
+	if (pull && pull.head.repo.full_name !== REPOSITORY) {
+		console.log(`PR #${pull.number} is from a fork; not reporting`);
+		return undefined;
+	}
+	return pull;
+}
+
+// Build log lines, oldest first. Vercel keeps them as events; only the ones
+// with text are log lines.
+async function fetchBuildLog() {
+	const url = new URL(
+		`https://api.vercel.com/v3/deployments/${DEPLOYMENT_ID}/events`
+	);
+	url.searchParams.set('limit', '-1');
+	url.searchParams.set('direction', 'forward');
+	if (process.env.VERCEL_TEAM_ID) {
+		url.searchParams.set('teamId', process.env.VERCEL_TEAM_ID);
+	}
+	const events = await fetchJson(url, {
+		authorization: `Bearer ${process.env.VERCEL_TOKEN}`
+	});
+	return events
+		.map(event => event.payload?.text ?? event.text)
+		.filter(text => typeof text === 'string')
+		.flatMap(text => text.replace(/\n$/, '').split('\n'));
+}
+
+// The failure is at the end of the log; keep the tail within GitHub's comment
+// size limit. A four-backtick fence so lines containing ``` cannot break out.
+function failureBody(logLines) {
+	let tail = logLines.slice(-MAX_LOG_LINES);
+	while (tail.length > 1 && tail.join('\n').length > MAX_LOG_CHARS) {
+		tail = tail.slice(1);
+	}
+	const omitted = logLines.length - tail.length;
+	return [
+		MARKER,
+		'### ❌ The Vercel build failed for this PR',
+		'',
+		'Vercel only shows build logs to members of its team, so here is the end of the log.',
+		'Run `npm run build` locally to reproduce.',
+		'',
+		'<details>',
+		`<summary>Build log${omitted > 0 ? ` (last ${tail.length} of ${logLines.length} lines)` : ''}</summary>`,
+		'',
+		'````',
+		...tail,
+		'````',
+		'',
+		'</details>',
+		''
+	].join('\n');
+}
+
+async function main() {
+	for (const name of [
+		'DEPLOYMENT_ID',
+		'DEPLOYMENT_STATE',
+		'COMMIT_SHA',
+		'GH_TOKEN',
+		'GITHUB_REPOSITORY'
+	]) {
+		if (!process.env[name]) {
+			throw new Error(`Missing required environment variable ${name}`);
+		}
+	}
+	if (!['error', 'success'].includes(DEPLOYMENT_STATE)) {
+		throw new Error(`Unexpected DEPLOYMENT_STATE ${DEPLOYMENT_STATE}`);
+	}
+
+	const pull = await findPullRequest();
+	if (!pull) {
+		console.log(`No open PR with head ${COMMIT_SHA}; nothing to do`);
+		return;
+	}
+
+	const comments = await githubList(
+		`/repos/${REPOSITORY}/issues/${pull.number}/comments`
+	);
+	const existing = comments.find(comment => comment.body.startsWith(MARKER));
+
+	// Comment only when the build failed, or an earlier failure is resolved
+	let body;
+	if (DEPLOYMENT_STATE === 'error') {
+		if (!process.env.VERCEL_TOKEN) {
+			throw new Error('VERCEL_TOKEN is required to read the build log');
+		}
+		body = failureBody(await fetchBuildLog());
+	} else if (existing) {
+		body = `${MARKER}\n### ✅ The Vercel build that failed on an earlier revision of this PR passes\n`;
+	} else {
+		console.log(`PR #${pull.number} has no failed build to resolve`);
+		return;
+	}
+
+	if (DRY_RUN) {
+		console.log(
+			`[dry-run] would ${existing ? 'update' : 'create'} comment on PR #${pull.number}:\n`
+		);
+		console.log(body);
+	} else if (existing) {
+		console.log(`Updating comment ${existing.id} on PR #${pull.number}`);
+		await github(
+			'PATCH',
+			`/repos/${REPOSITORY}/issues/comments/${existing.id}`,
+			{body}
+		);
+	} else {
+		console.log(`Commenting on PR #${pull.number}`);
+		await github(
+			'POST',
+			`/repos/${REPOSITORY}/issues/${pull.number}/comments`,
+			{body}
+		);
+	}
+}
+
+main().catch(error => {
+	console.error(error);
+	process.exit(2);
+});

From 7333b3f00d5ab92b6a7465850e208efb60110026 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 04:11:15 -0600
Subject: [PATCH 12/14] test: break links, spelling, and redirects to exercise
 every PR check (do not merge)

Check links: three absolute self-links (one to a moved page) and a dead
external link on one line; a missing page, missing heading, and wrong-case
path on the next; and the "Symbol search" heading renamed to break the
inbound anchor link from search-based-code-navigation.mdx.

Spell check: nine misspellings on one line, five of them block-list words.

Check redirects: one broken entry per category (shadowed page, #fragment
source, /docs prefix, duplicate source, chain, missing page, missing heading).

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
---
 cspell-allow-list.txt              |  1 +
 docs/admin/markdown.mdx            |  3 ---
 docs/admin/tls_ssl.mdx             |  5 +++++
 docs/batch-changes/server-side.mdx |  2 +-
 docs/code-search/features.mdx      |  8 +++++++-
 src/data/redirects.ts              | 20 ++++++++++++++++++++
 6 files changed, 34 insertions(+), 5 deletions(-)
 delete mode 100644 docs/admin/markdown.mdx
 create mode 100644 docs/admin/tls_ssl.mdx

diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index 4df15e327..c4ec98dda 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -599,3 +599,4 @@ YOURUSERNAME
 Zaporizhzhia
 Zoekt
 zoomable
+aardvark # test entry for the sorted-list check (will be reverted)
diff --git a/docs/admin/markdown.mdx b/docs/admin/markdown.mdx
deleted file mode 100644
index 3308e167f..000000000
--- a/docs/admin/markdown.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
-# Sourcegraph-flavored Markdown
-
-Sourcegraph uses [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) anywhere Markdown is rendered. We like this [Markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for reference.
diff --git a/docs/admin/tls_ssl.mdx b/docs/admin/tls_ssl.mdx
new file mode 100644
index 000000000..11c9a2c37
--- /dev/null
+++ b/docs/admin/tls_ssl.mdx
@@ -0,0 +1,5 @@
+---
+title: TLS test page
+---
+
+# TLS test page
diff --git a/docs/batch-changes/server-side.mdx b/docs/batch-changes/server-side.mdx
index c301fa1d8..537b21f59 100644
--- a/docs/batch-changes/server-side.mdx
+++ b/docs/batch-changes/server-side.mdx
@@ -37,7 +37,7 @@ Running batch changes server-side has been tested to run a simple **45K changese
 
 By default, docker on mac will build docker images for `linux/arm64`, which will result in errors when running server-side because executors provide `linux/amd64` hosts. If you're creating your own images to run in batch changes, this can be a problem. Use the `--platform linux/amd64` flag with `docker build` to build images compatible with the server-side host.
 
-## Using file mounts with server-side execution
+## Using file mounts with SSBC
 
 <Callout type="note">
 	Running a batch spec server-side with file mounts is currently only
diff --git a/docs/code-search/features.mdx b/docs/code-search/features.mdx
index b86a4d8f3..7a1b47dd5 100644
--- a/docs/code-search/features.mdx
+++ b/docs/code-search/features.mdx
@@ -45,7 +45,7 @@ Searching over commit messages is supported in Sourcegraph by adding `type:commi
 
 See our [query syntax](/code-search/queries#diff-and-commit-searches-only) documentation for a comprehensive list of supported parameters.
 
-## Symbol search
+## Symbol lookup
 
 Searching for symbols makes it easier to find specific functions, variables, and more. Use the `type:symbol` filter to search for symbol results. Symbol results also appear in typeahead suggestions, so you can jump directly to symbols by name. When on an [indexed](/admin/search#indexed-search) commit, it uses Zoekt. Otherwise it uses the [symbols service](/code-search/types/symbol)
 
@@ -148,3 +148,9 @@ This file picker is useful when comparing branches with thousands of changed fil
 
 - When viewing a file or directory, press the `y` key to expand the URL to its canonical form (with the full 40-character Git commit SHA).
 - To share a link to multi-line range in a file, click on the starting line number and shift-click on the ending line number (in the left-hand gutter).
+
+Test links for the check-links workflow (will be reverted): [site config](https://sourcegraph.com/docs/admin/config/site-config), [search](//www.sourcegraph.com/docs/code-search/), [moved page](http://docs.sourcegraph.com/admin/http_https_configuration#sourcegraph-via-docker-compose-caddy-2), [dead external](https://github.com/sourcegraph/docs/blob/main/this-file-does-not-exist.md), [live external](https://github.com/sourcegraph/docs).
+
+More test links, none of which the check can fix for you: [missing page](/code-search/no-such-page), [missing heading](/code-search/features#no-such-heading), [wrong case](/Code-Search/queries).
+
+Test paragraph for the spell check workflow (will be reverted): Sourcegraph indexs every repositry acros your organization, so seach results are alwasy fresh. It keeps compatability with the databse layer, and the exector runs each batch spec in its own contiainer.
diff --git a/src/data/redirects.ts b/src/data/redirects.ts
index c1a548241..2652334e0 100644
--- a/src/data/redirects.ts
+++ b/src/data/redirects.ts
@@ -1,6 +1,22 @@
 import {TECHNICAL_CHANGELOG_RSS_URL} from './constants';
 
 const redirectsData = [
+	{
+		source: "/docs/old-prefixed",
+		destination: "/code-ownership"
+	},
+	{
+		source: "/old-chain",
+		destination: "/admin/http_https_configuration"
+	},
+	{
+		source: "/old-ownership",
+		destination: "/code-ownershp"
+	},
+	{
+		source: "/old-ownership#anchor",
+		destination: "/code-ownership"
+	},
 	{
 		source: '/integration/img/disable_extension.png',
 		destination: '/integration/img/disable-extension.png'
@@ -5896,6 +5912,10 @@ const redirectsData = [
 		source: '/code-search/how-to/create-search-context-graphql',
 		destination: '/api'
 	},
+	{
+		source: "/admin/http_https_configuration",
+		destination: "/self-hosted/http-https-configuration"
+	}
 ];
 
 const updatedRedirectsData = redirectsData.map(redirect => {

From 402e125af8621ff0d98eef800378ca8cc138d2d3 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:21:03 -0600
Subject: [PATCH 13/14] test: apply the fixes the PR checks suggested

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 docs/code-search/features.mdx |  6 +++---
 src/data/redirects.ts         | 16 ++++------------
 2 files changed, 7 insertions(+), 15 deletions(-)

diff --git a/docs/code-search/features.mdx b/docs/code-search/features.mdx
index 7a1b47dd5..5e546876b 100644
--- a/docs/code-search/features.mdx
+++ b/docs/code-search/features.mdx
@@ -149,8 +149,8 @@ This file picker is useful when comparing branches with thousands of changed fil
 - When viewing a file or directory, press the `y` key to expand the URL to its canonical form (with the full 40-character Git commit SHA).
 - To share a link to multi-line range in a file, click on the starting line number and shift-click on the ending line number (in the left-hand gutter).
 
-Test links for the check-links workflow (will be reverted): [site config](https://sourcegraph.com/docs/admin/config/site-config), [search](//www.sourcegraph.com/docs/code-search/), [moved page](http://docs.sourcegraph.com/admin/http_https_configuration#sourcegraph-via-docker-compose-caddy-2), [dead external](https://github.com/sourcegraph/docs/blob/main/this-file-does-not-exist.md), [live external](https://github.com/sourcegraph/docs).
+Test links for the check-links workflow (will be reverted): [site config](/admin/config/site-config), [search](/code-search), [moved page](/self-hosted/http-https-configuration#sourcegraph-via-docker-compose-caddy-2), [dead external](https://github.com/sourcegraph/docs/blob/main/this-file-does-not-exist.md), [live external](https://github.com/sourcegraph/docs).
 
-More test links, none of which the check can fix for you: [missing page](/code-search/no-such-page), [missing heading](/code-search/features#no-such-heading), [wrong case](/Code-Search/queries).
+More test links, none of which the check can fix for you: [missing page](/code-search/no-such-page), [missing heading](/code-search/features#no-such-heading), [wrong case](/code-search/queries).
 
-Test paragraph for the spell check workflow (will be reverted): Sourcegraph indexs every repositry acros your organization, so seach results are alwasy fresh. It keeps compatability with the databse layer, and the exector runs each batch spec in its own contiainer.
+Test paragraph for the spell check workflow (will be reverted): Sourcegraph indexes every repository arcos your organization, so search results are always fresh. It keeps compatibility with the database layer, and the executor runs each batch spec in its own container.
diff --git a/src/data/redirects.ts b/src/data/redirects.ts
index 2652334e0..fde6ff628 100644
--- a/src/data/redirects.ts
+++ b/src/data/redirects.ts
@@ -2,19 +2,15 @@ import {TECHNICAL_CHANGELOG_RSS_URL} from './constants';
 
 const redirectsData = [
 	{
-		source: "/docs/old-prefixed",
-		destination: "/code-ownership"
+		source: '/old-prefixed',
+		destination: '/code-ownership'
 	},
 	{
-		source: "/old-chain",
-		destination: "/admin/http_https_configuration"
+		source: '/old-chain',
+		destination: '/self-hosted/http-https-configuration'
 	},
 	{
 		source: "/old-ownership",
-		destination: "/code-ownershp"
-	},
-	{
-		source: "/old-ownership#anchor",
 		destination: "/code-ownership"
 	},
 	{
@@ -5912,10 +5908,6 @@ const redirectsData = [
 		source: '/code-search/how-to/create-search-context-graphql',
 		destination: '/api'
 	},
-	{
-		source: "/admin/http_https_configuration",
-		destination: "/self-hosted/http-https-configuration"
-	}
 ];
 
 const updatedRedirectsData = redirectsData.map(redirect => {

From 406a779472b8010923ead04906540df6f85781b5 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:22:32 -0600
Subject: [PATCH 14/14] test: fix what the checks could only report

Restore the deleted page, the shadowed redirect page, and both renamed
headings; point the dead links at real targets; fix the one misspelling
CSpell guessed wrong (across, not arcos); drop the unsorted allow-list entry.

Amp-Thread-ID: https://ampcode.com/threads/T-01a08fee-74b4-76dc-aaf9-d1245d68fdc9
Co-authored-by: Amp <amp@ampcode.com>
---
 cspell-allow-list.txt              | 1 -
 docs/admin/markdown.mdx            | 3 +++
 docs/admin/tls_ssl.mdx             | 5 -----
 docs/batch-changes/server-side.mdx | 2 +-
 docs/code-search/features.mdx      | 8 ++++----
 5 files changed, 8 insertions(+), 11 deletions(-)
 create mode 100644 docs/admin/markdown.mdx
 delete mode 100644 docs/admin/tls_ssl.mdx

diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index c4ec98dda..4df15e327 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -599,4 +599,3 @@ YOURUSERNAME
 Zaporizhzhia
 Zoekt
 zoomable
-aardvark # test entry for the sorted-list check (will be reverted)
diff --git a/docs/admin/markdown.mdx b/docs/admin/markdown.mdx
new file mode 100644
index 000000000..3308e167f
--- /dev/null
+++ b/docs/admin/markdown.mdx
@@ -0,0 +1,3 @@
+# Sourcegraph-flavored Markdown
+
+Sourcegraph uses [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) anywhere Markdown is rendered. We like this [Markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for reference.
diff --git a/docs/admin/tls_ssl.mdx b/docs/admin/tls_ssl.mdx
deleted file mode 100644
index 11c9a2c37..000000000
--- a/docs/admin/tls_ssl.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
----
-title: TLS test page
----
-
-# TLS test page
diff --git a/docs/batch-changes/server-side.mdx b/docs/batch-changes/server-side.mdx
index 537b21f59..c301fa1d8 100644
--- a/docs/batch-changes/server-side.mdx
+++ b/docs/batch-changes/server-side.mdx
@@ -37,7 +37,7 @@ Running batch changes server-side has been tested to run a simple **45K changese
 
 By default, docker on mac will build docker images for `linux/arm64`, which will result in errors when running server-side because executors provide `linux/amd64` hosts. If you're creating your own images to run in batch changes, this can be a problem. Use the `--platform linux/amd64` flag with `docker build` to build images compatible with the server-side host.
 
-## Using file mounts with SSBC
+## Using file mounts with server-side execution
 
 <Callout type="note">
 	Running a batch spec server-side with file mounts is currently only
diff --git a/docs/code-search/features.mdx b/docs/code-search/features.mdx
index 5e546876b..3f3655bf2 100644
--- a/docs/code-search/features.mdx
+++ b/docs/code-search/features.mdx
@@ -45,7 +45,7 @@ Searching over commit messages is supported in Sourcegraph by adding `type:commi
 
 See our [query syntax](/code-search/queries#diff-and-commit-searches-only) documentation for a comprehensive list of supported parameters.
 
-## Symbol lookup
+## Symbol search
 
 Searching for symbols makes it easier to find specific functions, variables, and more. Use the `type:symbol` filter to search for symbol results. Symbol results also appear in typeahead suggestions, so you can jump directly to symbols by name. When on an [indexed](/admin/search#indexed-search) commit, it uses Zoekt. Otherwise it uses the [symbols service](/code-search/types/symbol)
 
@@ -149,8 +149,8 @@ This file picker is useful when comparing branches with thousands of changed fil
 - When viewing a file or directory, press the `y` key to expand the URL to its canonical form (with the full 40-character Git commit SHA).
 - To share a link to multi-line range in a file, click on the starting line number and shift-click on the ending line number (in the left-hand gutter).
 
-Test links for the check-links workflow (will be reverted): [site config](/admin/config/site-config), [search](/code-search), [moved page](/self-hosted/http-https-configuration#sourcegraph-via-docker-compose-caddy-2), [dead external](https://github.com/sourcegraph/docs/blob/main/this-file-does-not-exist.md), [live external](https://github.com/sourcegraph/docs).
+Test links for the check-links workflow (will be reverted): [site config](/admin/config/site-config), [search](/code-search), [moved page](/self-hosted/http-https-configuration#sourcegraph-via-docker-compose-caddy-2), [live external](https://github.com/sourcegraph/docs/blob/main/README.md), [live external](https://github.com/sourcegraph/docs).
 
-More test links, none of which the check can fix for you: [missing page](/code-search/no-such-page), [missing heading](/code-search/features#no-such-heading), [wrong case](/code-search/queries).
+More test links, none of which the check can fix for you: [page](/code-search/queries), [heading](/code-search/features#symbol-search), [right case](/code-search/queries).
 
-Test paragraph for the spell check workflow (will be reverted): Sourcegraph indexes every repository arcos your organization, so search results are always fresh. It keeps compatibility with the database layer, and the executor runs each batch spec in its own container.
+Test paragraph for the spell check workflow (will be reverted): Sourcegraph indexes every repository across your organization, so search results are always fresh. It keeps compatibility with the database layer, and the executor runs each batch spec in its own container.