Repository navigation
feat(seo): derive search metadata from the catalogue and publish browse hubs - #72
Merged
Merged
Conversation
…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
force-pushed
the
feat/seo-metadata
branch
from
November 16, 2026 10:24
ece2ac3 to
cc84df9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 therelease 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
lastmodsources (derived fromsrc/pagesrather than a hand-keptmap, 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:seoinjust validateasserts one H1, uniquenon-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 andcatalogue checks, a 366-page build, discovery validation, SEO checks, link crawl,
generated-output checks and 52 built-output tests.