[warp-agent-staging]

Summary

On every docs page, the raw HTML that follows </h1> currently holds:

• the Copy-page menu labels ("Copy Copy page Copy page as Markdown for LLMs … Open in ChatGPT ↗"),
• a hidden <template id="page-markdown-content"> carrying the page's entire raw MDX source,
• and only after both of those, the page description.

On /factories/ the description starts about 17 KB after </h1>. Across 21 sampled pages, 0 of 21 put the description first, and the hidden template adds 325 KB, 202 KB of it on /changelog/2026/ alone.

This PR changes no prose, and the title row looks the same:

• CustomPageTitle.astro: the source order is now H1, then p.page-subtitle, then the Copy menu (wrapped in data-nosnippet). A CSS grid keeps the Copy button to the right of the H1, with the description spanning the full width underneath.
• CopyPageButton.astro: the full-page <template> and its MDX cleanup helpers are removed.
  • Copy page as Markdown for LLMs now fetches the page's .md twin on click, which is the "durable fix" the existing code comment called for. It uses ClipboardItem with a pending blob and falls back to fetch then writeText. The toast now reports failures too.
  • View as Markdown opens the .md URL directly.
  • Copy agent prompt, Open in ChatGPT and Open in Claude are unchanged.
• scripts/validate-page-title-order.mjs (npm run test:page-title-order, added to CI after the homepage JSON-LD check) fails the build if any built page:
  • still has the template;
  • doesn't have the subtitle as the H1's next element;
  • has a subtitle that doesn't match the meta description;
  • doesn't start the first 200 characters after </h1> with the description.

Why (AR-20261028-3, weekly AEO autoresearch)

• Mechanism (hypothesis): answer engines ground short answers on the title plus a snippet anchored at the H1. Search Engine Land's write-up of RESONEO's study (2026-08-17) reports this for ChatGPT, and Bing's webmaster guidelines also ask for key information early. Today that snippet is menu labels.
• Comparison: Cursor, GitHub and Cline docs go straight from the H1 to the description.
• Metric: Peec ChatGPT citation rate on docs.warp.dev URLs. The baseline will be read from Peec history for the 14 days before merge.
• Prediction: +10–20% relative within 21 days of deploy, falsified if there's no increase. Guard: docs Search Console CTR doesn't fall.
• Caveat: this is a prediction, not a measured result.

Verification (local production build)

• npm ci, npm run typecheck (0 errors), npm run build and all test:* scripts pass: heading-vars, heading-tocs (3,392 entries), tracking-redirect, tracking-routes, homepage-json-ld, kapa-webmcp, kapa-support-escalation, and the new page-title-order check across 400 pages.
• On the same 21 URLs, production had 0/21 description-first and 325,220 template bytes; this branch has 21/21 and 0. Total HTML across the 21 pages drops from 3.49 MB to 3.00 MB.
• Browser check (Chromium, 1280px and 390px):
  • The title row matches production, including a two-line H1 at 390px.
  • Copy page fetched /factories.md (200), showed "Copied!", and the pasted text was the page markdown.
  • Copy agent prompt, View as Markdown and the Open in ChatGPT and Claude links all work.

Risks

• Copy page now needs a network request. If .md is unavailable it shows "Copy failed" instead of copying raw MDX.
• The copied text is now the rendered .md twin rather than raw MDX: components are rendered and variables resolved, and it starts with the llms.txt note lines.
• Tested in Chromium only. Safari's ClipboardItem path is untested.

Preview checks follow in a comment.

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 28, 2026 4:47pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  View origin

[warp-agent-staging]

Preview checks (autoresearch AR-20261028-3)

• Lede check (lede_check.py, the raw HTML a non-JS crawler receives), on a seeded sample of 21 sitemap pages compared with production:
  • description directly after </h1>: 0/21 on production, 21/21 on this preview
  • page-markdown-content template bytes: 219,412 → 0 (the 35 KB left is the small theme-icon and agent-prompt templates)
  • H1 inside <main> on all pages; no regressions
  • example, /: the text after the H1 used to be "Copy Copy page Copy page as Markdown for LLMs…" and is now "Warp combines a modern terminal, coding agents, cloud automation, and software f…"
• verify_site.py --compare, control preview (docs#957's branch, recent main) vs this preview: 0 regressions. The only note is that "software factory" now appears 55 words earlier on /.
• ora, this preview vs the control preview (contract 1.37): canonical 58 → 58, required tier 59.2% → 59.2%, no check changed.

Posted by a Warp agent

[warp-agent-staging]

Addressed review findings in the latest commit:

• Validator coverage: the floor is no longer a fixed 100 pages. validate-page-title-order.mjs now requires 98% of the source docs (src/content/docs/**/*.md{,x}), which today is at least 392 of 400 pages. The 2% tolerance leaves room for a future page that legitimately renders without a title row, while a change that drops the row from many pages now fails. It passes locally on 400 pages.
• Accessibility: the copy toast is now a polite live region (role="status" aria-live="polite"), so screen readers announce both "Copied!" and "Copy failed".

npm run typecheck reports 0 errors.

Posted by a Warp agent