SEO panel fields silently ignored unless the page wires getSeoMeta (footgun for content editors)

[DavidPivert]

Problem

The admin exposes a full SEO panel (SEO title, meta description, OG image, canonical URL, "hide from search engines"/noindex). Content editors fill it in expecting it to take effect.

But these fields live on entry.data.seo and have no effect unless the page template explicitly calls getSeoMeta (or getContentSeo). A site author who hand-rolls a collection detail page like:

<title>{entry.data.title}</title>
<meta name="description" content={entry.data.excerpt} />

silently bypasses the entire panel — including the noindex toggle, which is an indexing/correctness risk, not just cosmetic.

Why it's a trap

• The breakage is invisible: no error, no warning — the panel just does nothing.
• The editor and the developer are often different people; the editor has no way to know the field is dead.
• The docs (skills/building-emdash-site/references/site-features.md) only show getSeoMeta for a posts page and never state that every content detail page must wire it or the panel is inert.

I hit this on a real site: only the scaffolded posts page used getSeoMeta; four hand-written collection pages (albums, interviews, covers, collabs) ignored the panel entirely. Editors had filled SEO titles/descriptions that were never rendered, and the noindex toggle did nothing.

Suggestions (any of)

1. Docs: add a prominent gotcha in site-features.md — "the SEO panel is only honored if your page calls getSeoMeta; hand-written title/description bypass it silently." (Happy to PR this — see below.)
2. Ergonomic helper: a <SeoHead entry={...} defaults={{ title, description, image }} /> component, or let getSeoMeta accept defaultTitle/defaultDescription. Today its only fallbacks are data.title/data.excerpt, so authors with computed titles (e.g. "Maeta — {title} (cover of {artist})") must drop down to getContentSeo and merge panel-vs-default by hand.
3. Dev-mode warning: when an entry has non-empty data.seo fields but the rendered page never read them, log a warning in dev.

Environment

• emdash (current main), Astro + Cloudflare Workers template.

[swissky]

Triage: the data-layer prerequisite here was fixed by #1285 — entry.data.seo is populated on the single-entry loader path, so getSeoMeta works as documented… except it wasn't documented anywhere in the public docs (only in the in-repo skill references). #1900 adds a "Rendering SEO Panel Data" section to the Querying Content guide with a full example and a caution box on exactly this footgun (hand-rolled meta tags bypass the panel including noindex). The remaining idea from this issue — surfacing a warning to editors when the template doesn't consume SEO — needs a maintainer design call, since the server can't easily know what a template renders.

[ascorbic]

I wonder if we should add it by default to the EmDashHead component

[swissky]

Status of the three suggestions:

1. Docs gotcha — covered by docs(seo): clarify the SEO panel is only honored if the page wires getSeoMeta #1519 (reporter's PR for the skill reference) and docs: document rendering SEO panel data via getSeoMeta (#1518) #1900 (docs guide, documents rendering panel data via getSeoMeta). Both open.
2. Ergonomic helper — now implemented in feat(seo): getSeoMeta accepts defaultTitle/defaultDescription (#1518) #1957: getSeoMeta accepts defaultTitle / defaultDescription, ranking between the panel value and the data.title/data.excerpt fallback. Panel values (incl. an editor-set SEO title) always win, so computed-title pages no longer need to hand-roll <title> or merge via getContentSeo. Design notes in discussion getSeoMeta defaults: implement suggestion 2 from #1518 #1956.
3. Dev-mode warning — not tackled yet; needs render-path tracking ("was data.seo read during this render?") which is a bigger mechanism. Worth revisiting if the docs + helper don't defuse the footgun.

[swissky]

Agreed, that's the better fix — done in #1963. EmDashHead now fetches the entry's SEO panel row whenever the page context references a content entry and layers it between plugin contributions and the template-provided base metadata, so panel values apply by default and plugins can still override.

Two notes on scope:

• The lookup is gated on the collection's hasSeo flag (via the cached collection info), so non-SEO collections don't pay an extra query.
• The <title> element itself stays with the template — a head component can't replace it. seo.title feeds og:title/twitter:title; for the document title getSeoMeta() is still the way (which is where the defaultTitle option from feat(seo): getSeoMeta accepts defaultTitle/defaultDescription (#1518) #1957 comes in).