inconsistent SEO descriptions #28509
Description
Existing documentation URL(s)
Many docs pages have no description in frontmatter, even though AGENTS.md recommends it for SEO.
In Framework guides alone, only 5 of 33 files have description (Next.js, Nuxt, Analog, SvelteKit, static Next.js); the rest (including Docusaurus, Astro, Vue, Remix, etc.) do not.
That hurts:
- Search snippets and click-through
- Consistency with the style guide and “how we docs” metadata
- Parity with framework guides that already have descriptions
we already have tooling (bin/generate-descriptions.ts) but it is not in CI and depends on a local Worker, so the gap persists and new pages are often added without descriptions.
What changes are you suggesting?
For now:
add descriptions for SEO in each page omitted.
That would align the whole docs set with the existing trend (Nuxt, Next, etc. already use descriptions) and make the existing generate-descriptions script something you run to fix reported pages rather than to discover them by hand.
After:
New check in CI (e.g. in bin/ or a small GH action) that fails the build when any doc in src/content/docs (or a chosen subset) has no description. This forces descriptions to be added or explicitly opted out (e.g. via a allowlist for nav-only or special pages).
Additional information
If the implementation is needed, I'd love to take this as a contributor.
thanks, cloudflare team.
cc: @pedrosousa
No response