From 865c94d9eeb3ec5dd7ad15ea7a589df6245fe3fe Mon Sep 17 00:00:00 2001
From: "warp-agent-staging[bot]"
 <240773466+warp-agent-staging[bot]@users.noreply.github.com>
Date: Wed, 4 Nov 2026 16:22:11 +0000
Subject: [PATCH 1/2] AR-20261104-2: canonical Link header + frontmatter on
 docs .md twins; drop /404/ from llms files

---
 .github/workflows/ci.yml                      |  9 ++
 astro.config.mjs                              |  4 +-
 package.json                                  |  3 +
 scripts/markdown-canonical-headers.test.mjs   | 48 ++++++++++
 scripts/validate-llms-txt.mjs                 | 53 +++++++++++
 scripts/validate-markdown-twins.mjs           | 94 +++++++++++++++++++
 src/components/CopyPageButton.astro           |  7 +-
 src/integrations/docs-markdown-integration.js | 45 ++++++++-
 .../docs-markdown-integration.test.js         | 72 ++++++++++++++
 src/lib/docs-markdown.js                      | 12 +++
 vercel.json                                   | 18 ++++
 11 files changed, 360 insertions(+), 5 deletions(-)
 create mode 100644 scripts/markdown-canonical-headers.test.mjs
 create mode 100644 scripts/validate-llms-txt.mjs
 create mode 100644 scripts/validate-markdown-twins.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ddca77de7..01f5f4c42 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -141,6 +141,9 @@ jobs:
       - name: Test agent discovery catalog
         run: npm run test:agent-discovery
 
+      - name: Test Markdown twin canonical headers
+        run: npm run test:markdown-canonical
+
       - name: Build site
         run: npm run build
 
@@ -153,6 +156,12 @@ jobs:
       - name: Validate homepage JSON-LD
         run: npm run test:homepage-json-ld
 
+      - name: Validate llms files list only sitemap pages
+        run: npm run test:llms-txt
+
+      - name: Validate Markdown twin frontmatter
+        run: npm run test:markdown-twins
+
       - name: Validate page title order
         run: npm run test:page-title-order
 
diff --git a/astro.config.mjs b/astro.config.mjs
index deb71f7ca..077614928 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -210,7 +210,9 @@ export default defineConfig({
 				// due to their size. The upstream plugin only applies `exclude` to
 				// llms-small.txt; our patch (patches/starlight-llms-txt+0.8.1.patch)
 				// extends it to llms-full.txt and custom sets as well.
-				exclude: ['support-and-community/community/open-source-licenses'],
+				// '404' is the not-found page; it is not documentation, and listing
+				// it sent agents to https://docs.warp.dev/404/.
+				exclude: ['support-and-community/community/open-source-licenses', '404'],
 					// This string is the first thing an AI engine reads about Warp, so it
 					// carries the product lineup. Kept in sync with the rename and with
 					// launches: it said "the Oz platform" until the 8/18 rename, which
diff --git a/package.json b/package.json
index 3938524e0..d96f3acff 100644
--- a/package.json
+++ b/package.json
@@ -22,10 +22,13 @@
     "test:docs-markdown": "node --test src/integrations/docs-markdown-integration.test.js",
     "test:tracking-redirect": "node --test scripts/tracking-redirect.test.mjs",
     "test:agent-discovery": "node --test scripts/agent-discovery.test.mjs",
+    "test:markdown-canonical": "node --test scripts/markdown-canonical-headers.test.mjs",
     "test:tracking-routes": "node scripts/validate-tracking-routes.mjs",
     "test:kapa-webmcp": "node --test src/lib/kapa-webmcp.test.mjs",
     "test:kapa-support-escalation": "node --test src/lib/kapa-support-escalation.test.mjs",
     "test:homepage-json-ld": "node scripts/validate-homepage-json-ld.mjs",
+    "test:llms-txt": "node scripts/validate-llms-txt.mjs",
+    "test:markdown-twins": "node scripts/validate-markdown-twins.mjs",
     "test:page-title-order": "node scripts/validate-page-title-order.mjs",
     "postinstall": "patch-package"
   },
diff --git a/scripts/markdown-canonical-headers.test.mjs b/scripts/markdown-canonical-headers.test.mjs
new file mode 100644
index 000000000..8b8cc3117
--- /dev/null
+++ b/scripts/markdown-canonical-headers.test.mjs
@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { test } from 'node:test';
+// Same converter Vercel uses to turn vercel.json `headers` into routes
+// (installed through @astrojs/vercel), so the test exercises the real
+// source pattern and `:path` substitution instead of a reimplementation.
+import { getTransformedRoutes } from '@vercel/routing-utils';
+import { DOCS_ORIGIN } from '../src/lib/site.js';
+
+const vercelConfig = JSON.parse(await readFile(new URL('../vercel.json', import.meta.url), 'utf8'));
+const { routes, error } = getTransformedRoutes({ headers: vercelConfig.headers });
+
+/** Returns every Link header value Vercel would add to a response for `pathname`. */
+function linkHeadersFor(pathname) {
+	const values = [];
+	for (const route of routes ?? []) {
+		const key = Object.keys(route.headers ?? {}).find((name) => name.toLowerCase() === 'link');
+		if (!key) continue;
+		const match = pathname.match(new RegExp(route.src));
+		if (!match) continue;
+		values.push(route.headers[key].replace(/\$(\d+)/g, (_, index) => match[Number(index)] ?? ''));
+	}
+	return values;
+}
+
+const canonical = (url) => `<${url}>; rel="canonical"`;
+
+test('vercel.json headers compile', () => {
+	assert.equal(error, null);
+});
+
+test('every Markdown twin points to its HTML page with a canonical Link header', () => {
+	const cases = {
+		'/index.md': `${DOCS_ORIGIN}/`,
+		'/factories.md': `${DOCS_ORIGIN}/factories/`,
+		'/terminal/blocks/block-basics.md': `${DOCS_ORIGIN}/terminal/blocks/block-basics/`,
+		'/changelog/2026.md': `${DOCS_ORIGIN}/changelog/2026/`,
+	};
+	for (const [pathname, htmlUrl] of Object.entries(cases)) {
+		assert.deepEqual(linkHeadersFor(pathname), [canonical(htmlUrl)], pathname);
+	}
+});
+
+test('HTML pages and other files get no canonical Link header', () => {
+	for (const pathname of ['/', '/factories/', '/factories', '/llms.txt', '/openapi.yaml', '/sitemap-0.xml']) {
+		assert.deepEqual(linkHeadersFor(pathname), [], pathname);
+	}
+});
diff --git a/scripts/validate-llms-txt.mjs b/scripts/validate-llms-txt.mjs
new file mode 100644
index 000000000..75e7eb2b3
--- /dev/null
+++ b/scripts/validate-llms-txt.mjs
@@ -0,0 +1,53 @@
+// Checks the generated llms files after `npm run build`.
+//
+// Every page that llms-full.txt, llms-small.txt, or a /_llms-txt/*.txt set
+// includes carries a "Canonical page: [path](url)" line (see
+// patches/starlight-llms-txt+0.8.1.patch). Each of those URLs must be a page
+// listed in the sitemap, so the files never send agents to the 404 page or to a
+// page that search engines are told does not exist.
+//
+// Usage: node scripts/validate-llms-txt.mjs [outputDir]
+// outputDir defaults to .vercel/output/static.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const outputDir = path.resolve(process.argv[2] ?? '.vercel/output/static');
+
+const sitemapFiles = (await readdir(outputDir)).filter((name) => /^sitemap-\d+\.xml$/.test(name));
+if (sitemapFiles.length === 0) {
+	console.error(`No sitemap-N.xml in ${outputDir}. Run npm run build first.`);
+	process.exit(1);
+}
+const sitemapUrls = new Set();
+for (const name of sitemapFiles) {
+	const xml = await readFile(path.join(outputDir, name), 'utf8');
+	for (const [, loc] of xml.matchAll(/<loc>([^<]+)<\/loc>/g)) sitemapUrls.add(loc.trim());
+}
+
+const llmsFiles = ['llms-full.txt', 'llms-small.txt'];
+try {
+	for (const name of await readdir(path.join(outputDir, '_llms-txt'))) {
+		if (name.endsWith('.txt')) llmsFiles.push(path.join('_llms-txt', name));
+	}
+} catch {
+	// No custom sets configured.
+}
+
+const problems = [];
+let checked = 0;
+for (const name of llmsFiles) {
+	const text = await readFile(path.join(outputDir, name), 'utf8');
+	for (const [, url] of text.matchAll(/Canonical page: \[[^\]]*\]\(([^)\s]+)\)/g)) {
+		checked += 1;
+		if (!sitemapUrls.has(url)) problems.push(`${name}: ${url} is not in the sitemap`);
+	}
+}
+
+if (checked === 0) problems.push('No "Canonical page:" lines found; the llms-txt patch may not have applied.');
+
+if (problems.length > 0) {
+	console.error(`llms files list ${problems.length} page(s) that are not in the sitemap:`);
+	for (const problem of [...new Set(problems)]) console.error(`  ${problem}`);
+	process.exit(1);
+}
+console.log(`OK: ${checked} canonical page entries across ${llmsFiles.length} llms files are all in the sitemap.`);
diff --git a/scripts/validate-markdown-twins.mjs b/scripts/validate-markdown-twins.mjs
new file mode 100644
index 000000000..7801dfb82
--- /dev/null
+++ b/scripts/validate-markdown-twins.mjs
@@ -0,0 +1,94 @@
+// Checks the generated Markdown twins after `npm run build`.
+//
+// Every sitemap page that advertises a twin with
+// `<link rel="alternate" type="text/markdown">` has one at `<path>.md`
+// (`/` -> `/index.md`), written by
+// src/integrations/docs-markdown-integration.js. Each twin must exist and start
+// with YAML frontmatter whose `canonical` is the HTML page's own
+// `<link rel="canonical">`, so the twin, its `Link` header (vercel.json), and
+// the HTML page all name the same URL.
+//
+// Usage: node scripts/validate-markdown-twins.mjs [outputDir]
+// outputDir defaults to .vercel/output/static.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DOCS_ORIGIN } from '../src/lib/site.js';
+
+const outputDir = path.resolve(process.argv[2] ?? '.vercel/output/static');
+
+const sitemapFiles = (await readdir(outputDir)).filter((name) => /^sitemap-\d+\.xml$/.test(name));
+if (sitemapFiles.length === 0) {
+	console.error(`No sitemap-N.xml in ${outputDir}. Run npm run build first.`);
+	process.exit(1);
+}
+const pageUrls = new Set();
+for (const name of sitemapFiles) {
+	const xml = await readFile(path.join(outputDir, name), 'utf8');
+	for (const [, loc] of xml.matchAll(/<loc>([^<]+)<\/loc>/g)) pageUrls.add(loc.trim());
+}
+
+const problems = [];
+let checked = 0;
+let skipped = 0;
+for (const url of pageUrls) {
+	if (!url.startsWith(`${DOCS_ORIGIN}/`)) continue;
+	const pagePath = new URL(url).pathname.replace(/\/$/, '');
+	const htmlFile = path.join(outputDir, pagePath, 'index.html');
+	const markdownFile = path.join(outputDir, pagePath ? `${pagePath}.md` : 'index.md');
+
+	let html;
+	try {
+		html = await readFile(htmlFile, 'utf8');
+	} catch {
+		problems.push(`${url}: missing ${path.relative(outputDir, htmlFile)}`);
+		continue;
+	}
+	// Pages without a twin, such as the API reference at /api/, do not advertise one.
+	if (!/<link rel="alternate" type="text\/markdown"/.test(html)) {
+		skipped += 1;
+		continue;
+	}
+	let markdown;
+	try {
+		markdown = await readFile(markdownFile, 'utf8');
+	} catch {
+		problems.push(`${url}: advertises ${path.relative(outputDir, markdownFile)}, which was not generated`);
+		continue;
+	}
+	checked += 1;
+
+	const htmlCanonical = html.match(/<link rel="canonical" href="([^"]+)"/)?.[1];
+	const frontmatter = markdown.match(/^---\n([\s\S]*?)\n---\n/)?.[1];
+	if (!frontmatter) {
+		problems.push(`${url}: .md twin does not start with YAML frontmatter`);
+		continue;
+	}
+	const fields = {};
+	for (const line of frontmatter.split('\n')) {
+		const index = line.indexOf(': ');
+		try {
+			fields[line.slice(0, index)] = JSON.parse(line.slice(index + 2));
+		} catch {
+			problems.push(`${url}: frontmatter line is not a quoted value: ${line}`);
+		}
+	}
+	if (!fields.title) problems.push(`${url}: frontmatter has no title`);
+	if (fields.canonical !== url) {
+		problems.push(`${url}: frontmatter canonical is ${fields.canonical}`);
+	}
+	if (htmlCanonical && htmlCanonical !== fields.canonical) {
+		problems.push(`${url}: HTML canonical ${htmlCanonical} differs from twin canonical ${fields.canonical}`);
+	}
+}
+
+if (checked === 0) problems.push('No Markdown twins were checked.');
+
+if (problems.length > 0) {
+	console.error(`${problems.length} Markdown twin problem(s):`);
+	for (const problem of problems.slice(0, 50)) console.error(`  ${problem}`);
+	process.exit(1);
+}
+console.log(
+	`OK: ${checked} Markdown twins start with frontmatter that points to their HTML page ` +
+		`(${skipped} sitemap page(s) advertise no twin).`,
+);
diff --git a/src/components/CopyPageButton.astro b/src/components/CopyPageButton.astro
index 72cfde37f..99bcc00f7 100644
--- a/src/components/CopyPageButton.astro
+++ b/src/components/CopyPageButton.astro
@@ -140,6 +140,8 @@ const claudeUrl = `https://claude.ai/new?q=${prompt}`;
 <template id="agent-prompt-content">{agentPromptText}</template>
 
 <script>
+  import { stripFrontmatter } from '../lib/docs-markdown.js';
+
   // `DOMContentLoaded` is used instead of `astro:page-load` because
   // `<ClientRouter />` is not enabled site-wide (see CustomHead.astro).
   // `astro:page-load` only fires when View Transitions are active.
@@ -185,7 +187,10 @@ const claudeUrl = `https://claude.ai/new?q=${prompt}`;
     async function fetchMarkdown(): Promise<string> {
       const res = await fetch(markdownUrl(), { headers: { Accept: 'text/markdown' } });
       if (!res.ok) throw new Error(`Markdown fetch failed: ${res.status}`);
-      const text = await res.text();
+      // The twin opens with YAML frontmatter (title, description, canonical
+      // URL) for crawlers and agents. The copied page keeps its previous
+      // shape, which already starts with the title and description.
+      const text = stripFrontmatter(await res.text());
       if (!text.trim()) throw new Error('Markdown fetch returned an empty body');
       return text;
     }
diff --git a/src/integrations/docs-markdown-integration.js b/src/integrations/docs-markdown-integration.js
index 97ae89d67..eb953960b 100644
--- a/src/integrations/docs-markdown-integration.js
+++ b/src/integrations/docs-markdown-integration.js
@@ -33,7 +33,9 @@ async function generateMarkdownFiles(outputRoot) {
 
 		const markdownPath = getMarkdownOutputPath(outputRoot, relativeHtmlPath);
 		const html = await readFile(htmlFile, 'utf8');
-		const markdown = convertHtmlToMarkdown(html);
+		const markdown = convertHtmlToMarkdown(html, {
+			canonicalUrl: getCanonicalUrl(relativeHtmlPath),
+		});
 		if (!markdown) continue;
 
 		await mkdir(path.dirname(markdownPath), { recursive: true });
@@ -72,6 +74,15 @@ function isDocHtmlFile(relativeHtmlPath) {
 	return relativeHtmlPath === 'index.html' || relativeHtmlPath.endsWith('/index.html');
 }
 
+// The HTML page a twin was generated from: `factories/index.html` ->
+// https://docs.warp.dev/factories/, `index.html` -> https://docs.warp.dev/.
+// vercel.json sends the same URL as a `Link: <...>; rel="canonical"` header on
+// every `.md` response (see scripts/markdown-canonical-headers.test.mjs).
+function getCanonicalUrl(relativeHtmlPath) {
+	const htmlDir = path.dirname(relativeHtmlPath).split(path.sep).join('/');
+	return htmlDir === '.' ? `${DOCS_ORIGIN}/` : `${DOCS_ORIGIN}/${htmlDir}/`;
+}
+
 function getMarkdownOutputPath(outputRoot, relativeHtmlPath) {
 	if (relativeHtmlPath === 'index.html') {
 		return path.join(outputRoot, 'index.md');
@@ -81,12 +92,19 @@ function getMarkdownOutputPath(outputRoot, relativeHtmlPath) {
 	return path.join(outputRoot, `${htmlDir}.md`);
 }
 
-function convertHtmlToMarkdown(html) {
+/**
+ * @param {string} html
+ * @param {{ canonicalUrl?: string }} [options] `canonicalUrl` is the HTML page
+ *   the twin duplicates; it falls back to the page's `<link rel="canonical">`.
+ */
+function convertHtmlToMarkdown(html, { canonicalUrl } = {}) {
 	const { document } = parseHTML(html);
 	const title = document.querySelector('h1[data-page-title], main h1')?.textContent?.trim();
 	const description = document.querySelector('meta[name="description"]')?.getAttribute('content')?.trim();
 	const contentRoot = document.querySelector('main .sl-markdown-content');
 	if (!title || !contentRoot) return '';
+	const canonical =
+		canonicalUrl ?? document.querySelector('link[rel="canonical"]')?.getAttribute('href')?.trim();
 
 	const clone = /** @type {HTMLElement} */ (contentRoot.cloneNode(true));
 	expandAgentOnlyTemplates(clone);
@@ -107,7 +125,28 @@ function convertHtmlToMarkdown(html) {
 		sections.push(markdownBody);
 	}
 
-	return `${sections.join('\n\n').trim()}\n`;
+	const frontmatter = buildFrontmatter({
+		title: normalizeWhitespace(title),
+		description: description ? normalizeWhitespace(description) : undefined,
+		canonical,
+	});
+	return `${frontmatter}${sections.join('\n\n').trim()}\n`;
+}
+
+/**
+ * YAML frontmatter as the first bytes of the twin, so tools that read
+ * Markdown metadata get the page title, summary, and the HTML page to cite.
+ * Values are written as JSON strings, which are valid YAML double-quoted
+ * scalars, so colons, quotes, `#`, and leading symbols cannot change the
+ * meaning of the YAML. Empty values are omitted.
+ *
+ * @param {Record<string, string | undefined>} fields
+ */
+function buildFrontmatter(fields) {
+	const lines = Object.entries(fields)
+		.filter(([, value]) => value)
+		.map(([key, value]) => `${key}: ${JSON.stringify(value)}`);
+	return `---\n${lines.join('\n')}\n---\n\n`;
 }
 
 /**
diff --git a/src/integrations/docs-markdown-integration.test.js b/src/integrations/docs-markdown-integration.test.js
index 9b0a183af..731a18f9d 100644
--- a/src/integrations/docs-markdown-integration.test.js
+++ b/src/integrations/docs-markdown-integration.test.js
@@ -5,6 +5,7 @@ import path from 'node:path';
 import test from 'node:test';
 import { pathToFileURL } from 'node:url';
 import docsMarkdownIntegration, { convertHtmlToMarkdown } from './docs-markdown-integration.js';
+import { stripFrontmatter } from '../lib/docs-markdown.js';
 
 function createPage(content) {
 	return `
@@ -153,6 +154,77 @@ test('build hook writes Markdown without changing browser HTML or hidden tab sta
 	assert.match(markdown, /## Jira\n\nHidden\./);
 });
 
+test('build hook points each twin\'s frontmatter at its HTML page', async (t) => {
+	const directory = await mkdtemp(path.join(os.tmpdir(), 'docs-markdown-canonical-'));
+	t.after(() => rm(directory, { recursive: true, force: true }));
+	await mkdir(path.join(directory, 'terminal', 'blocks'), { recursive: true });
+	const page = createPage('<p>Body.</p>');
+	await writeFile(path.join(directory, 'index.html'), page);
+	await writeFile(path.join(directory, 'terminal', 'blocks', 'index.html'), page);
+	await writeFile(path.join(directory, '404.html'), page);
+
+	await docsMarkdownIntegration().hooks['astro:build:generated']({
+		dir: pathToFileURL(`${directory}/`), logger: { info() {} },
+	});
+
+	const home = await readFile(path.join(directory, 'index.md'), 'utf8');
+	const nested = await readFile(path.join(directory, 'terminal', 'blocks.md'), 'utf8');
+	assert.ok(home.startsWith('---\ntitle: "Test page"\ndescription: "Test description."\ncanonical: "https://docs.warp.dev/"\n---\n\n> '));
+	assert.ok(nested.startsWith('---\n'));
+	assert.match(nested, /\ncanonical: "https:\/\/docs\.warp\.dev\/terminal\/blocks\/"\n---\n/);
+	await assert.rejects(readFile(path.join(directory, '404.md'), 'utf8'));
+});
+
+test('writes YAML frontmatter first, with values quoted and the body unchanged', () => {
+	const title = 'Rules: "AGENTS.md" #1 & more';
+	const description = "- Leading dash: it's a 'test' \\ with backslash";
+	const html = `<html><head>
+		<meta name="description" content="${description.replaceAll('"', '&quot;')}">
+		<link rel="canonical" href="https://docs.warp.dev/agents/rules/">
+		</head><body><main><h1 data-page-title>${title.replaceAll('&', '&amp;').replaceAll('"', '&quot;')}</h1>
+		<div class="sl-markdown-content"><p>Body text.</p></div></main></body></html>`;
+	const markdown = convertHtmlToMarkdown(html);
+
+	const match = markdown.match(/^---\n([\s\S]*?)\n---\n\n/);
+	assert.ok(match, 'frontmatter must be the first bytes');
+	// Each value is a JSON string, which YAML reads as a double-quoted scalar.
+	const fields = Object.fromEntries(match[1].split('\n').map((line) => {
+		const index = line.indexOf(': ');
+		return [line.slice(0, index), JSON.parse(line.slice(index + 2))];
+	}));
+	assert.deepEqual(fields, {
+		title,
+		description,
+		canonical: 'https://docs.warp.dev/agents/rules/',
+	});
+	assert.equal(
+		markdown.slice(match[0].length),
+		'> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).\n' +
+			'> Markdown versions of each page are available by appending .md to any URL.\n\n' +
+			`# ${title}\n\n${description}\n\nBody text.\n`,
+	);
+});
+
+test('omits frontmatter fields that have no value', () => {
+	const markdown = convertHtmlToMarkdown(
+		'<main><h1 data-page-title>No description</h1><div class="sl-markdown-content"><p>Body.</p></div></main>',
+		{ canonicalUrl: 'https://docs.warp.dev/example/' },
+	);
+	assert.ok(markdown.startsWith('---\ntitle: "No description"\ncanonical: "https://docs.warp.dev/example/"\n---\n\n'));
+});
+
+test('stripFrontmatter returns the body the Copy page button copies', () => {
+	const markdown = convertHtmlToMarkdown(createPage('<p>Body.</p>'), {
+		canonicalUrl: 'https://docs.warp.dev/example/',
+	});
+	const copied = stripFrontmatter(markdown);
+	assert.ok(copied.startsWith('> For the complete documentation index'));
+	assert.doesNotMatch(copied, /^---|canonical:/m);
+	// Markdown without frontmatter, such as the dev endpoint's output, is unchanged.
+	assert.equal(stripFrontmatter('# Title\n\n---\n\nBody\n'), '# Title\n\n---\n\nBody\n');
+	assert.equal(stripFrontmatter('---\r\ntitle: "A"\r\n---\r\n\r\n# A\r\n'), '# A\r\n');
+});
+
 test('includes inert agent-only templates in generated Markdown', () => {
 	const html = `
 		<html>
diff --git a/src/lib/docs-markdown.js b/src/lib/docs-markdown.js
index 689480e7f..f50a86e5a 100644
--- a/src/lib/docs-markdown.js
+++ b/src/lib/docs-markdown.js
@@ -46,6 +46,18 @@ export function shouldServeMarkdown(request) {
 	return AGENT_USER_AGENT_TOKENS.some((token) => userAgent.includes(token));
 }
 
+/**
+ * Removes a leading YAML frontmatter block (`---` ... `---`) and the blank
+ * lines after it. Generated `.md` twins start with frontmatter for crawlers
+ * and agents; the Copy page button removes it because the copied body already
+ * starts with the page title and description.
+ *
+ * @param {string} markdown
+ */
+export function stripFrontmatter(markdown) {
+	return markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n(?:\r?\n)*/, '');
+}
+
 function normalizePathname(pathname) {
 	if (!pathname || pathname === '/') return '/';
 	const trimmedPath = pathname.replace(/\/+$/, '');
diff --git a/vercel.json b/vercel.json
index cc338d611..74c2aa08d 100644
--- a/vercel.json
+++ b/vercel.json
@@ -42,6 +42,24 @@
         }
       ]
     },
+    {
+      "source": "/index.md",
+      "headers": [
+        {
+          "key": "Link",
+          "value": "<https://docs.warp.dev/>; rel=\"canonical\""
+        }
+      ]
+    },
+    {
+      "source": "/:path((?!index\\.md$).+)\\.md",
+      "headers": [
+        {
+          "key": "Link",
+          "value": "<https://docs.warp.dev/:path/>; rel=\"canonical\""
+        }
+      ]
+    },
     {
       "source": "/:directory(_astro|assets)/:path(.*)",
       "headers": [

From d01c41fcb19ae10b06b1682700d259a30f864785 Mon Sep 17 00:00:00 2001
From: "warp-agent-staging[bot]"
 <240773466+warp-agent-staging[bot]@users.noreply.github.com>
Date: Wed, 4 Nov 2026 16:45:46 +0000
Subject: [PATCH 2/2] Emit canonical Link headers only for generated .md twins

Replace the vercel.json catch-all, which also labelled 404 responses for
any other .md request, with exact case-sensitive routes written into
.vercel/output/config.json after the build. Tighten the twin validator and
drop the transitive @vercel/routing-utils import.
---
 package.json                                  |  2 +-
 scripts/build-markdown-canonical-routes.mjs   | 63 +++++++++++++
 scripts/markdown-canonical-headers.test.mjs   | 94 +++++++++++++------
 scripts/validate-markdown-twins.mjs           | 64 +++++++++----
 src/integrations/docs-markdown-integration.js |  4 +-
 src/lib/markdown-canonical-routes.js          | 91 ++++++++++++++++++
 vercel.json                                   | 18 ----
 7 files changed, 268 insertions(+), 68 deletions(-)
 create mode 100644 scripts/build-markdown-canonical-routes.mjs
 create mode 100644 src/lib/markdown-canonical-routes.js

diff --git a/package.json b/package.json
index d96f3acff..ee0b97c6a 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
     "dev": "astro dev",
     "predev": "node scripts/generate-openapi-json.mjs",
     "build": "astro build",
-    "postbuild": "node scripts/build-tracking-middleware.mjs",
+    "postbuild": "node scripts/build-tracking-middleware.mjs && node scripts/build-markdown-canonical-routes.mjs",
     "prebuild": "node scripts/generate-openapi-json.mjs",
     "preview": "astro preview",
     "astro": "astro",
diff --git a/scripts/build-markdown-canonical-routes.mjs b/scripts/build-markdown-canonical-routes.mjs
new file mode 100644
index 000000000..524329e34
--- /dev/null
+++ b/scripts/build-markdown-canonical-routes.mjs
@@ -0,0 +1,63 @@
+// Adds canonical `Link` headers for the generated Markdown twins to the Vercel
+// build output. Runs from `postbuild`, after `astro build` writes
+// .vercel/output/config.json and the docs-markdown integration writes the twins.
+//
+// A twin is `<path>.md` (`index.md` for the homepage) whose HTML page,
+// `<path>/index.html`, advertises it with
+// `<link rel="alternate" type="text/markdown" href="/<path>.md">`. Only those
+// paths get the header, so 404 responses for other `.md` requests do not claim
+// a canonical page. Routes go before the filesystem phase, where vercel.json
+// headers also run, and use `continue` so the static file is still served.
+// See src/lib/markdown-canonical-routes.js.
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildMarkdownCanonicalRoutes } from '../src/lib/markdown-canonical-routes.js';
+
+const output = fileURLToPath(new URL('../.vercel/output/', import.meta.url));
+const staticDir = path.join(output, 'static');
+const configPath = path.join(output, 'config.json');
+
+/** @param {string} dir */
+async function* markdownFiles(dir) {
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const entryPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) yield* markdownFiles(entryPath);
+		else if (entry.isFile() && entry.name.endsWith('.md')) yield entryPath;
+	}
+}
+
+const twinPaths = [];
+for await (const file of markdownFiles(staticDir)) {
+	const twinPath = path.relative(staticDir, file).split(path.sep).join('/').slice(0, -'.md'.length);
+	const htmlFile = twinPath === 'index'
+		? path.join(staticDir, 'index.html')
+		: path.join(staticDir, twinPath, 'index.html');
+	let html;
+	try {
+		html = await readFile(htmlFile, 'utf8');
+	} catch {
+		continue;
+	}
+	if (html.includes(`<link rel="alternate" type="text/markdown" href="/${twinPath}.md"`)) {
+		twinPaths.push(twinPath);
+	}
+}
+if (twinPaths.length === 0) {
+	console.error('build-markdown-canonical-routes: no Markdown twins found in .vercel/output/static');
+	process.exit(1);
+}
+
+const config = JSON.parse(await readFile(configPath, 'utf8'));
+// Drop routes from an earlier run so rerunning the script does not duplicate them.
+const routes = config.routes.filter(
+	(route) => !(route.headers?.Link ?? '').endsWith('; rel="canonical"'),
+);
+const filesystemIndex = routes.findIndex((route) => route.handle === 'filesystem');
+const canonicalRoutes = buildMarkdownCanonicalRoutes(twinPaths);
+routes.splice(filesystemIndex === -1 ? routes.length : filesystemIndex, 0, ...canonicalRoutes);
+config.routes = routes;
+await writeFile(configPath, JSON.stringify(config, null, 2));
+console.log(
+	`build-markdown-canonical-routes: ${twinPaths.length} twins, ${canonicalRoutes.length} header routes`,
+);
diff --git a/scripts/markdown-canonical-headers.test.mjs b/scripts/markdown-canonical-headers.test.mjs
index 8b8cc3117..8fd4dfe03 100644
--- a/scripts/markdown-canonical-headers.test.mjs
+++ b/scripts/markdown-canonical-headers.test.mjs
@@ -1,48 +1,82 @@
 import assert from 'node:assert/strict';
 import { readFile } from 'node:fs/promises';
 import { test } from 'node:test';
-// Same converter Vercel uses to turn vercel.json `headers` into routes
-// (installed through @astrojs/vercel), so the test exercises the real
-// source pattern and `:path` substitution instead of a reimplementation.
-import { getTransformedRoutes } from '@vercel/routing-utils';
+import {
+	buildMarkdownCanonicalRoutes,
+	canonicalLinkValue,
+	linkHeadersFor,
+} from '../src/lib/markdown-canonical-routes.js';
 import { DOCS_ORIGIN } from '../src/lib/site.js';
 
-const vercelConfig = JSON.parse(await readFile(new URL('../vercel.json', import.meta.url), 'utf8'));
-const { routes, error } = getTransformedRoutes({ headers: vercelConfig.headers });
+const twins = [
+	'index',
+	'agents',
+	'factories',
+	'terminal/blocks/block-basics',
+	'changelog/2026',
+	'factories/api-and-sdk/troubleshooting/errors/conflict',
+];
+const routes = buildMarkdownCanonicalRoutes(twins);
 
-/** Returns every Link header value Vercel would add to a response for `pathname`. */
-function linkHeadersFor(pathname) {
-	const values = [];
-	for (const route of routes ?? []) {
-		const key = Object.keys(route.headers ?? {}).find((name) => name.toLowerCase() === 'link');
-		if (!key) continue;
-		const match = pathname.match(new RegExp(route.src));
-		if (!match) continue;
-		values.push(route.headers[key].replace(/\$(\d+)/g, (_, index) => match[Number(index)] ?? ''));
-	}
-	return values;
-}
-
-const canonical = (url) => `<${url}>; rel="canonical"`;
-
-test('vercel.json headers compile', () => {
-	assert.equal(error, null);
-});
-
-test('every Markdown twin points to its HTML page with a canonical Link header', () => {
+test('every generated twin points to its HTML page', () => {
 	const cases = {
 		'/index.md': `${DOCS_ORIGIN}/`,
+		'/agents.md': `${DOCS_ORIGIN}/agents/`,
 		'/factories.md': `${DOCS_ORIGIN}/factories/`,
 		'/terminal/blocks/block-basics.md': `${DOCS_ORIGIN}/terminal/blocks/block-basics/`,
 		'/changelog/2026.md': `${DOCS_ORIGIN}/changelog/2026/`,
+		'/factories/api-and-sdk/troubleshooting/errors/conflict.md':
+			`${DOCS_ORIGIN}/factories/api-and-sdk/troubleshooting/errors/conflict/`,
 	};
 	for (const [pathname, htmlUrl] of Object.entries(cases)) {
-		assert.deepEqual(linkHeadersFor(pathname), [canonical(htmlUrl)], pathname);
+		assert.deepEqual(linkHeadersFor(routes, pathname), [canonicalLinkValue(htmlUrl)], pathname);
+	}
+});
+
+test('paths that are not generated twins get no canonical Link header', () => {
+	for (const pathname of [
+		// HTML pages and other generated files
+		'/', '/factories/', '/factories', '/llms.txt', '/openapi.yaml', '/sitemap-0.xml',
+		// reserved and missing paths, which return 404
+		'/assets/not-a-twin.md', '/_astro/not-a-twin.md', '/.well-known/not-a-twin.md',
+		'/robots.md', '/not-a-twin.md', '/factories/missing.md', '/terminal/index.md',
+		// near misses
+		'/factories.md/', '/factories.mdx', '/factories.md.html', '/xfactories.md', '/factories-x.md',
+		'/terminal/blocks.md', '/index.md/extra',
+		// case variants: static files are case-sensitive, so these 404
+		'/AGENTS.md', '/Factories.md', '/INDEX.md', '/factories.MD',
+	]) {
+		assert.deepEqual(linkHeadersFor(routes, pathname), [], pathname);
+	}
+});
+
+test('large twin sets are split into bounded routes that still match exactly', () => {
+	const many = Array.from({ length: 600 }, (_, index) => `section-${index}/page-with-a-long-name-${index}`);
+	const manyRoutes = buildMarkdownCanonicalRoutes(many);
+	assert.ok(manyRoutes.length > 1);
+	for (const route of manyRoutes) {
+		assert.ok(route.src.length < 4000, `src is ${route.src.length} characters`);
+		assert.equal(route.caseSensitive, true);
+		assert.equal(route.continue, true);
 	}
+	for (const twin of [many[0], many[299], many[599]]) {
+		assert.deepEqual(linkHeadersFor(manyRoutes, `/${twin}.md`), [canonicalLinkValue(`${DOCS_ORIGIN}/${twin}/`)]);
+	}
+	assert.deepEqual(linkHeadersFor(manyRoutes, '/section-0.md'), []);
+});
+
+test('regex characters in a path are matched literally', () => {
+	const special = buildMarkdownCanonicalRoutes(['guides/c++', 'a.b']);
+	assert.deepEqual(linkHeadersFor(special, '/guides/c++.md'), [canonicalLinkValue(`${DOCS_ORIGIN}/guides/c++/`)]);
+	assert.deepEqual(linkHeadersFor(special, '/guides/cc.md'), []);
+	assert.deepEqual(linkHeadersFor(special, '/aXb.md'), []);
 });
 
-test('HTML pages and other files get no canonical Link header', () => {
-	for (const pathname of ['/', '/factories/', '/factories', '/llms.txt', '/openapi.yaml', '/sitemap-0.xml']) {
-		assert.deepEqual(linkHeadersFor(pathname), [], pathname);
+test('vercel.json adds no canonical Link header (generated routes own it)', async () => {
+	const vercelConfig = JSON.parse(await readFile(new URL('../vercel.json', import.meta.url), 'utf8'));
+	for (const entry of vercelConfig.headers ?? []) {
+		for (const header of entry.headers) {
+			assert.notEqual(header.key.toLowerCase(), 'link', entry.source);
+		}
 	}
 });
diff --git a/scripts/validate-markdown-twins.mjs b/scripts/validate-markdown-twins.mjs
index 7801dfb82..08fdddabd 100644
--- a/scripts/validate-markdown-twins.mjs
+++ b/scripts/validate-markdown-twins.mjs
@@ -1,20 +1,26 @@
 // Checks the generated Markdown twins after `npm run build`.
 //
-// Every sitemap page that advertises a twin with
-// `<link rel="alternate" type="text/markdown">` has one at `<path>.md`
-// (`/` -> `/index.md`), written by
-// src/integrations/docs-markdown-integration.js. Each twin must exist and start
-// with YAML frontmatter whose `canonical` is the HTML page's own
-// `<link rel="canonical">`, so the twin, its `Link` header (vercel.json), and
-// the HTML page all name the same URL.
+// For every sitemap page that advertises a twin with
+// `<link rel="alternate" type="text/markdown">`:
+// - the advertised href is the expected twin, `/<path>.md` (`/` -> `/index.md`);
+// - the HTML page has a `<link rel="canonical">`;
+// - the twin exists and starts with YAML frontmatter whose `canonical` equals
+//   both the sitemap URL and the HTML canonical, and it has a `title`;
+// - the routes in .vercel/output/config.json (written by
+//   scripts/build-markdown-canonical-routes.mjs) give the twin exactly one
+//   `Link: <HTML canonical>; rel="canonical"` header.
+// Paths that are not twins, including reserved directories, missing files, and
+// case variants, must get no canonical `Link` header.
 //
 // Usage: node scripts/validate-markdown-twins.mjs [outputDir]
-// outputDir defaults to .vercel/output/static.
+// outputDir defaults to .vercel/output.
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { canonicalLinkValue, linkHeadersFor } from '../src/lib/markdown-canonical-routes.js';
 import { DOCS_ORIGIN } from '../src/lib/site.js';
 
-const outputDir = path.resolve(process.argv[2] ?? '.vercel/output/static');
+const outputRoot = path.resolve(process.argv[2] ?? '.vercel/output');
+const outputDir = path.join(outputRoot, 'static');
 
 const sitemapFiles = (await readdir(outputDir)).filter((name) => /^sitemap-\d+\.xml$/.test(name));
 if (sitemapFiles.length === 0) {
@@ -26,6 +32,7 @@ for (const name of sitemapFiles) {
 	const xml = await readFile(path.join(outputDir, name), 'utf8');
 	for (const [, loc] of xml.matchAll(/<loc>([^<]+)<\/loc>/g)) pageUrls.add(loc.trim());
 }
+const { routes } = JSON.parse(await readFile(path.join(outputRoot, 'config.json'), 'utf8'));
 
 const problems = [];
 let checked = 0;
@@ -33,8 +40,9 @@ let skipped = 0;
 for (const url of pageUrls) {
 	if (!url.startsWith(`${DOCS_ORIGIN}/`)) continue;
 	const pagePath = new URL(url).pathname.replace(/\/$/, '');
+	const twinUrlPath = `${pagePath || '/index'}.md`;
 	const htmlFile = path.join(outputDir, pagePath, 'index.html');
-	const markdownFile = path.join(outputDir, pagePath ? `${pagePath}.md` : 'index.md');
+	const markdownFile = path.join(outputDir, twinUrlPath);
 
 	let html;
 	try {
@@ -44,20 +52,31 @@ for (const url of pageUrls) {
 		continue;
 	}
 	// Pages without a twin, such as the API reference at /api/, do not advertise one.
-	if (!/<link rel="alternate" type="text\/markdown"/.test(html)) {
+	const alternate = html.match(/<link rel="alternate" type="text\/markdown" href="([^"]*)"/);
+	if (!alternate) {
 		skipped += 1;
 		continue;
 	}
+	checked += 1;
+	if (alternate[1] !== twinUrlPath) {
+		problems.push(`${url}: advertises Markdown at ${alternate[1]}, expected ${twinUrlPath}`);
+	}
+	const htmlCanonical = html.match(/<link rel="canonical" href="([^"]+)"/)?.[1];
+	if (!htmlCanonical) problems.push(`${url}: HTML page has no <link rel="canonical">`);
+
+	const headers = linkHeadersFor(routes, twinUrlPath);
+	const expectedHeader = canonicalLinkValue(htmlCanonical ?? url);
+	if (headers.length !== 1 || headers[0] !== expectedHeader) {
+		problems.push(`${url}: ${twinUrlPath} Link headers are ${JSON.stringify(headers)}, expected [${expectedHeader}]`);
+	}
+
 	let markdown;
 	try {
 		markdown = await readFile(markdownFile, 'utf8');
 	} catch {
-		problems.push(`${url}: advertises ${path.relative(outputDir, markdownFile)}, which was not generated`);
+		problems.push(`${url}: advertises ${twinUrlPath}, which was not generated`);
 		continue;
 	}
-	checked += 1;
-
-	const htmlCanonical = html.match(/<link rel="canonical" href="([^"]+)"/)?.[1];
 	const frontmatter = markdown.match(/^---\n([\s\S]*?)\n---\n/)?.[1];
 	if (!frontmatter) {
 		problems.push(`${url}: .md twin does not start with YAML frontmatter`);
@@ -76,19 +95,30 @@ for (const url of pageUrls) {
 	if (fields.canonical !== url) {
 		problems.push(`${url}: frontmatter canonical is ${fields.canonical}`);
 	}
-	if (htmlCanonical && htmlCanonical !== fields.canonical) {
+	if (fields.canonical !== htmlCanonical) {
 		problems.push(`${url}: HTML canonical ${htmlCanonical} differs from twin canonical ${fields.canonical}`);
 	}
 }
 
 if (checked === 0) problems.push('No Markdown twins were checked.');
 
+const notTwins = [
+	'/', '/factories/', '/llms.txt', '/sitemap-0.xml', '/openapi.yaml',
+	'/assets/not-a-twin.md', '/_astro/not-a-twin.md', '/.well-known/not-a-twin.md',
+	'/robots.md', '/AGENTS.md', '/not-a-twin.md', '/Factories.md', '/INDEX.md', '/factories.MD',
+];
+for (const pathname of notTwins) {
+	const headers = linkHeadersFor(routes, pathname);
+	if (headers.length > 0) problems.push(`${pathname} is not a twin but gets Link ${JSON.stringify(headers)}`);
+}
+
 if (problems.length > 0) {
 	console.error(`${problems.length} Markdown twin problem(s):`);
 	for (const problem of problems.slice(0, 50)) console.error(`  ${problem}`);
 	process.exit(1);
 }
 console.log(
-	`OK: ${checked} Markdown twins start with frontmatter that points to their HTML page ` +
+	`OK: ${checked} Markdown twins have frontmatter and exactly one canonical Link header that match ` +
+		`their HTML page; ${notTwins.length} non-twin paths get none ` +
 		`(${skipped} sitemap page(s) advertise no twin).`,
 );
diff --git a/src/integrations/docs-markdown-integration.js b/src/integrations/docs-markdown-integration.js
index eb953960b..d8e54c9e4 100644
--- a/src/integrations/docs-markdown-integration.js
+++ b/src/integrations/docs-markdown-integration.js
@@ -76,8 +76,8 @@ function isDocHtmlFile(relativeHtmlPath) {
 
 // The HTML page a twin was generated from: `factories/index.html` ->
 // https://docs.warp.dev/factories/, `index.html` -> https://docs.warp.dev/.
-// vercel.json sends the same URL as a `Link: <...>; rel="canonical"` header on
-// every `.md` response (see scripts/markdown-canonical-headers.test.mjs).
+// scripts/build-markdown-canonical-routes.mjs sends the same URL as a
+// `Link: <...>; rel="canonical"` header on each twin's response.
 function getCanonicalUrl(relativeHtmlPath) {
 	const htmlDir = path.dirname(relativeHtmlPath).split(path.sep).join('/');
 	return htmlDir === '.' ? `${DOCS_ORIGIN}/` : `${DOCS_ORIGIN}/${htmlDir}/`;
diff --git a/src/lib/markdown-canonical-routes.js b/src/lib/markdown-canonical-routes.js
new file mode 100644
index 000000000..3e4d60df7
--- /dev/null
+++ b/src/lib/markdown-canonical-routes.js
@@ -0,0 +1,91 @@
+// Canonical `Link` headers for the generated Markdown twins.
+//
+// Each twin (`/factories.md`, `/index.md`) duplicates an HTML page, so its
+// response carries `Link: <https://docs.warp.dev/factories/>; rel="canonical"`.
+// The header is emitted only for twins the build generated: a pattern such as
+// `/:path.md` in vercel.json would also label 404 responses for any other
+// `.md` request. scripts/build-markdown-canonical-routes.mjs writes these routes
+// into .vercel/output/config.json after `astro build`.
+import { DOCS_ORIGIN } from './site.js';
+
+// Keeps each route's `src` regex well below Vercel's per-pattern size limit.
+const MAX_SOURCE_LENGTH = 3500;
+
+/** @param {string} url */
+export const canonicalLinkValue = (url) => `<${url}>; rel="canonical"`;
+
+/**
+ * @param {string} twinPath twin path without the leading slash or `.md`
+ *   (`factories`, `terminal/blocks`, or `index` for the homepage)
+ */
+export function canonicalUrlForTwin(twinPath) {
+	return twinPath === 'index' ? `${DOCS_ORIGIN}/` : `${DOCS_ORIGIN}/${twinPath}/`;
+}
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Builds Build Output API routes that add the canonical `Link` header to the
+ * listed twins and to nothing else. Paths are grouped into a few alternation
+ * routes; `$1` in the header value is the matched path. Matching is
+ * case-sensitive because the static files are.
+ *
+ * @param {string[]} twinPaths see `canonicalUrlForTwin`
+ */
+export function buildMarkdownCanonicalRoutes(twinPaths) {
+	const routes = [];
+	const paths = [...new Set(twinPaths)].sort();
+	if (paths.includes('index')) {
+		routes.push({
+			src: '^/index\\.md$',
+			headers: { Link: canonicalLinkValue(canonicalUrlForTwin('index')) },
+			caseSensitive: true,
+			continue: true,
+		});
+	}
+
+	let group = [];
+	let length = 0;
+	const flush = () => {
+		if (group.length === 0) return;
+		routes.push({
+			src: `^/(${group.join('|')})\\.md$`,
+			headers: { Link: canonicalLinkValue(`${DOCS_ORIGIN}/$1/`) },
+			caseSensitive: true,
+			continue: true,
+		});
+		group = [];
+		length = 0;
+	};
+	for (const twinPath of paths) {
+		if (twinPath === 'index') continue;
+		const pattern = escapeRegExp(twinPath);
+		if (length + pattern.length + 1 > MAX_SOURCE_LENGTH) flush();
+		group.push(pattern);
+		length += pattern.length + 1;
+	}
+	flush();
+	return routes;
+}
+
+/**
+ * Returns every `Link` header value the given routes add to a response for
+ * `pathname`, using Vercel's route semantics: `src` is a regex matched
+ * case-insensitively unless `caseSensitive` is set, and `$N` in a header value
+ * is replaced with capture group N.
+ *
+ * @param {Array<{ src?: string, headers?: Record<string, string>, caseSensitive?: boolean }>} routes
+ * @param {string} pathname
+ */
+export function linkHeadersFor(routes, pathname) {
+	const values = [];
+	for (const route of routes) {
+		if (!route.src || !route.headers) continue;
+		const key = Object.keys(route.headers).find((name) => name.toLowerCase() === 'link');
+		if (!key) continue;
+		const match = pathname.match(new RegExp(route.src, route.caseSensitive ? '' : 'i'));
+		if (!match) continue;
+		values.push(route.headers[key].replace(/\$(\d+)/g, (_, index) => match[Number(index)] ?? ''));
+	}
+	return values;
+}
diff --git a/vercel.json b/vercel.json
index 74c2aa08d..cc338d611 100644
--- a/vercel.json
+++ b/vercel.json
@@ -42,24 +42,6 @@
         }
       ]
     },
-    {
-      "source": "/index.md",
-      "headers": [
-        {
-          "key": "Link",
-          "value": "<https://docs.warp.dev/>; rel=\"canonical\""
-        }
-      ]
-    },
-    {
-      "source": "/:path((?!index\\.md$).+)\\.md",
-      "headers": [
-        {
-          "key": "Link",
-          "value": "<https://docs.warp.dev/:path/>; rel=\"canonical\""
-        }
-      ]
-    },
     {
       "source": "/:directory(_astro|assets)/:path(.*)",
       "headers": [