Skip to content

feat(seo): derive search metadata from the catalogue and publish browse hubs - #72

Merged
kieronlanning merged 1 commit into
mainfrom
feat/seo-metadata
Nov 16, 2026
Merged

kieronlanning merged 1 commit into
mainfrom
feat/seo-metadata

Conversation

@kieronlanning

Copy link
Copy Markdown
Contributor

feat(seo): derive search metadata from the catalogue and publish browse hubs

Titles were the page's own name, so a documentation page never said which product
it documents and a project page carried none of the words a reader searches with.
Every <title> and meta description is now derived from the catalogue and the
release cache, and the derived title is budgeted to the ~70 characters a result
shows: the folder trail, then the word "documentation", then part of the page
title are given up in that order — never the subject itself, and never in a way
that lets two pages collapse onto one title.

Two page families publish the metadata the catalogue already had — /topics//
and /categories// (a hub exists once two projects share it) plus
/packages/ — and every topic chip on a project or documentation page links to its
hub, so the browse surface is reachable from the pages a reader lands on.
Documentation pages carry TechArticle + BreadcrumbList; project pages carry
SoftwareSourceCode + SoftwareApplication.

Also fixes the lastmod sources (derived from src/pages rather than a hand-kept
map, so /examples/astroc4/ no longer claims the build time) and that page's empty
<title>, which front-matter props never reached the MDX layout to fill.

Enforcement: bun run check:seo in just validate asserts one H1, unique
non-empty titles, self-referencing canonicals, documentation titles that name their
project and valid JSON-LD against the built site; length guidance stays advisory.

Recorded in ADR 0015 and in the consumer skills, which now also require a product
repository's README to link its published documentation.

Version 0.11.0: this is a feature, not a content-only update.

Verified: just validate — format, lint, astro check, 446 unit tests, asset and
catalogue checks, a 366-page build, discovery validation, SEO checks, link crawl,
generated-output checks and 52 built-output tests.

…se hubs

Titles were the page's own name, so a documentation page never said which product
it documents and a project page carried none of the words a reader searches with.
Every `<title>` and meta description is now derived from the catalogue and the
release cache, and the derived title is budgeted to the ~70 characters a result
shows: the folder trail, then the word "documentation", then part of the page
title are given up in that order — never the subject itself, and never in a way
that lets two pages collapse onto one title.

Two page families publish the metadata the catalogue already had — /topics/<topic>/
and /categories/<category>/ (a hub exists once two projects share it) plus
/packages/ — and every topic chip on a project or documentation page links to its
hub, so the browse surface is reachable from the pages a reader lands on.
Documentation pages carry TechArticle + BreadcrumbList; project pages carry
SoftwareSourceCode + SoftwareApplication.

Also fixes the `lastmod` sources (derived from `src/pages` rather than a hand-kept
map, so `/examples/astroc4/` no longer claims the build time) and that page's empty
`<title>`, which front-matter props never reached the MDX layout to fill.

Enforcement: `bun run check:seo` in `just validate` asserts one H1, unique
non-empty titles, self-referencing canonicals, documentation titles that name their
project and valid JSON-LD against the built site; length guidance stays advisory.

Recorded in ADR 0015 and in the consumer skills, which now also require a product
repository's README to link its published documentation.

Version 0.11.0: this is a feature, not a content-only update.

Verified: `just validate` — format, lint, astro check, 446 unit tests, asset and
catalogue checks, a 366-page build, discovery validation, SEO checks, link crawl,
generated-output checks and 52 built-output tests.
@kieronlanning
kieronlanning merged commit 42e542d into main Nov 16, 2026
1 check passed
@kieronlanning
kieronlanning deleted the feat/seo-metadata branch November 16, 2026 10:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant