[AEO] Clean page headlines in JSON-LD schema

[pranavsekhar]

Summary

• Use the clean page title for the JSON-LD headline instead of the browser title with its product/site suffix.
• Preserve existing visible <title> and SEO title behavior.
• Keep custom head-title overrides while removing their site suffix from structured data.
• Add focused unit coverage and update the locked JSON-LD snapshot.

Before:

"headline": "Get started - CLI · Cloudflare Workers docs"

After:

"headline": "Get started - CLI"

Tests

• pnpm exec vitest run src/util/page-head.node.test.ts
• pnpm run check
• pnpm run lint
• pnpm run format:core:check

Documentation checklist

• The change adheres to the documentation style guide.

[cloudflare-docs-bot]

Review

⚠️ 1 warning found in commit 9eb3d5f.

👉 Fix in your agent 👈

Fix the following review findings in PR #33509 (https://github.com/cloudflare/cloudflare-docs/pull/33509).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Warnings (1)

#### CR-1dc86d7a5411 · Headline suffix stripping misses real separators
- **File:** `src/util/page-head.ts` line 14
- **Issue:** resolveBaseTitle only strips a " | " separator, but title overrides in the repo also use other separators. E.g. src/content/docs/use-cases/{ai,saas,apis,performance,...}/index.mdx have `title: Performance` with `head: - tag: title, content: Performance · Use cases`, and cloudflare-for-saas uses `content: Plans — Cloudflare for SaaS`. For these pages resolvePageHeadline returns "Performance · Use cases" / "Plans — Cloudflare for SaaS", keeping the section/product suffix the PR and the JSDoc on lines 36-37 promise to remove ("always the clean semantic page title without an SEO, product, or site suffix"). The clean frontmatter title is available as the `title` argument but is only used when there is no override.
- **Fix:** Make the headline derivation robust to the separators actually used in the repo's title overrides (" | ", " · ", " — ", " - "), or fall back to / prefer the frontmatter `title` (the semantic title) instead of parsing the `<title>` override, and add a test for the "Performance · Use cases" pattern.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (1)

File

Issue

src/util/page-head.ts line 14

Headline suffix stripping misses real separators — resolveBaseTitle only strips a " | " separator, but title overrides in the repo also use other separators. E.g. src/content/docs/use-cases/{ai,saas,apis,performance,...}/index.mdx have title: Performance with head: - tag: title, content: Performance · Use cases, and cloudflare-for-saas uses content: Plans — Cloudflare for SaaS. For these pages resolvePageHeadline returns "Performance · Use cases" / "Plans — Cloudflare for SaaS", keeping the section/product suffix the PR and the JSDoc on lines 36-37 promise to remove ("always the clean semantic page title without an SEO, product, or site suffix"). The clean frontmatter title is available as the title argument but is only used when there is no override. Fix: Make the headline derivation robust to the separators actually used in the repo's title overrides (" | ", " · ", " — ", " - "), or fall back to / prefer the frontmatter title (the semantic title) instead of parsing the <title> override, and add a test for the "Performance · Use cases" pattern.

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[mvvmm]

/bonk will you review this finding and resolve it if accurate and appropriate: #33509 (comment)

[ask-bonk]

Verdict: Finding CR-1dc86d7a5411 is accurate, but only the second proposed fix is sound

Finding	Verdict	Reasoning
resolveBaseTitle only strips `"	", missing " · ", " — ", " - "` overrides	Agree
Fix option 1: robust multi-separator stripping	Disagree	Actively harmful. Splitting prefix-style overrides on the first separator loses the real title: Workers RPC — Visibility and Security Model (workers/runtime-apis/rpc/visibility.mdx:8) would become Workers RPC.
Fix option 2: prefer the frontmatter title	Agree	The frontmatter title is the clean semantic title (equals the visible H1) in every case I checked — Performance, Plans, Rule categories, Visibility and Security Model, FAQ, Glossary, etc. This is the right fix.

Required change (working tree is read-only, so I can't apply it)

This is a fork PR with a read-only working tree, so I can only describe the fix:

1. src/util/page-head.ts — make resolvePageHeadline return the semantic title instead of resolveBaseTitle(...):

   export function resolvePageHeadline({ title }: { title: string }): string {
   	return title;
   }

   Leave resolveBaseTitle/resolvePageTitle untouched so the visible <title> and SEO-title behavior is preserved (per the PR body).
2. src/components/PageHead.astro:114 — update the call to resolvePageHeadline({ title }) (drop titleOverride; otherwise TS flags the excess property).
3. src/util/page-head.node.test.ts — rework the "uses the clean base even when \<title>` preserves the raw override"test (itstitle: "raw"/"Model X (Author) | Workers AI"case doesn't match real overrides anyway — real model pages usedisplayName (author) · Cloudflare AI docs) to assert the semantic title wins, and add the requested Performance · Use cases→Performance` case.

Note: the headline change would also give model pages displayName as the headline (matching their visible H1), which is consistent with the PR's "clean semantic page title" goal.

github run

[mvvmm]

@pranavsekhar mind fixing up this finding?

[mvvmm]

Continuing this work on #33573 (its two commits are cherry-picked with credit to @pranavsekhar).

Triage of CR-1dc86d7a5411 ("Headline suffix stripping misses real separators"):

• Agree with the problem: head: title overrides use several separators (|, ·, —), so resolvePageHeadline kept suffixes on real pages — e.g. Performance · Use cases on the use-cases landing pages and Plans — Cloudflare for SaaS.
• Disagree with separator-based stripping: - and — also occur inside legitimate page titles in both orders — Get started - CLI (the flagship example in this PR), Workers RPC — Reserved Methods, Service bindings - HTTP. Splitting on them mangles real titles.
• Fix applied in fix: Use clean page titles for JSON-LD headlines #33573: derive the JSON-LD headline from the frontmatter title — the same value the page renders as its visible <h1> (on /workers/get-started/guide/ the H1 is CLI; "Get started - CLI" exists only in <title>/og tags). This is deterministic and keeps structured data consistent with on-page content. <title> behavior is unchanged.

Known tradeoff, noted in the PR body: pages whose override was richer than the H1 now get the bare frontmatter title (e.g. CLI instead of Get started - CLI); those are frontmatter content fixes rather than parsing heuristics.