diff --git a/.gitignore b/.gitignore index c73a61c..20a202e 100644 --- a/.gitignore +++ b/.gitignore @@ -165,6 +165,8 @@ PublishScripts/ **/packages/* # except build/, which is used as an MSBuild target. !**/packages/build/ +# except the site's own browse page, which is source rather than a restore target. +!src/src/pages/packages/** # Uncomment if necessary however generally it will be regenerated when needed #!**/packages/repositories.config # NuGet v3's project.json files produces more ignoreable files diff --git a/AGENTS.md b/AGENTS.md index 30558c6..09b8720 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,7 +53,8 @@ just validate ``` runs format-check → lint → typecheck → unit tests → asset checks → catalogue checks → build → -link crawl → generated-output checks → built-output tests. It is the same pipeline CI uses +discovery validation → search-metadata checks → link crawl → generated-output checks → built-output +tests. It is the same pipeline CI uses (`purview-build.json` → `bun run ci:build`), so a green `just validate` is the definition of "safe to merge". `just check-projects` is part of that chain and fails the build on catalogue drift. It also prints advisory observations (which never fail the build) when a project's declared `status` or @@ -186,9 +187,10 @@ src/src/data/projects/.yml` against a clone of its repository. | Docs aggregation | `src/src/lib/docs/aggregate.ts` (+ `frontmatter`, `links`, `sidebar`, `staleness`, `diagrams`, `redirect-file`) | | Consumer skills for product repositories | `skills/purview-site-{integration,docs,assessment}/` | | Release data | `src/src/lib/releases/*`, `src/scripts/fetch-releases.ts` | +| Search metadata and browse hubs (titles, descriptions, `/topics/`, `/categories/`, `/packages/`) | `src/src/lib/seo.ts`, `src/src/lib/hubs.ts` (ADR 0015) | | Mirrored project assets | `src/scripts/sync-assets.ts` (`assets:` in the manifest) | | Pages | `src/src/pages/{index,about,use-cases,docs,projects,releases}/` | | Live examples | `src/src/pages/examples/.mdx` (linked from the project page automatically) | -| Validation | `justfile`, `src/scripts/{check-links,check-generated,check-assets,check-projects}.ts` | +| Validation | `justfile`, `src/scripts/{check-links,check-generated,check-assets,check-projects,check-seo}.ts` | | Upstream-triggered rebuilds | `.github/workflows/upstream-refresh.yml`, `src/scripts/upstream-state.ts`, `src/src/lib/upstream.ts` (ADR 0014) | | Architecture decisions | `docs/decisions/*.md` | diff --git a/docs/decisions/0015-search-metadata-and-browse-hubs.md b/docs/decisions/0015-search-metadata-and-browse-hubs.md new file mode 100644 index 0000000..079d62a --- /dev/null +++ b/docs/decisions/0015-search-metadata-and-browse-hubs.md @@ -0,0 +1,146 @@ +# ADR 0015 — Search metadata derived from the catalogue, and browse hubs + +- Status: accepted +- Date: 2026-11-16 + +## Context + +ADR 0007 made the site *discoverable*: a partitioned sitemap, `robots.txt`, +per-project `llms.txt` bundles, `discover.json` and IndexNow. Crawlers could find +every URL, and they did. What they could not do was decide that any page answered +a question, because: + +1. **Titles were the page's own name.** A documentation page titled + `Union design | Purview Dev` omits the product it documents; a project page + titled `Unions — Purview Dev` omits every word a reader searches with. The + catalogue already knew those words (`shortDescription`, the package id, the + GitHub topics, the category) and used none of them in metadata. +2. **`og:type` was set globally to `website`** in the Astro config's `head` + array, which overrides the `article` Starlight emits for a documentation page. +3. **Every internal link into the documentation carried the same anchor text** + (`Read the guide →`), discarding the strongest on-page signal a docs page has. +4. **There was no browse surface.** The catalogue's metadata produced 17 project + pages and the docs mirror; a reader searching "c# source generator", + "value types" or "aspire" had no destination, and `/projects/` filtering is + client-side, so it is not a crawl path. +5. **The tags were decorative.** GitHub topics were rendered as chips on the + project and documentation pages and linked to nothing. + +The only structured data was a minimal `SoftwareSourceCode`/`TechArticle` pair, +and NuGet — the highest-authority place the packages appear — renders its links +`rel="nofollow"`. + +## Decisions + +### 1. Search metadata is derived from the catalogue, never hand-authored + +`src/src/lib/seo.ts` builds every `` and meta description from the +catalogue and the release cache: + +- a project page leads with the **product** (the primary package id) and the + keyword phrase taken from `shortDescription`; +- **a documentation page always names its project**, and the folder a page lives + in (ADR 0011) is part of the title and of the breadcrumb, because it is part of + the URL; +- a non-default documentation channel adds its version label, so the two versions + of one page never share a title (ADR 0009); +- descriptions prefer a sentence boundary when they must be truncated, instead of + ending mid-word with an ellipsis. + +The **visible H1 does not change**: the title is composed where every other piece +of search metadata is (`src/src/components/starlight/Head.astro`), from the +catalogue, the docs manifest and the page itself. The docs mirror therefore stays a +mirror of the *documentation* — it carries no site metadata — and a title change +needs no documentation re-sync. Starlight's own `<title>` is replaced, not appended +to, so no page can end up with two. + +Every derived title is budgeted to what a result actually shows (70 characters +including the brand, enforced by unit tests over the real catalogue). The parts are +dropped, or trimmed at a word boundary, in this order: the folder trail, the word +"documentation", then part of the page title. Nothing is ever dropped that +identifies the page — the project name in a documentation title, the product name +in a catalogue title — because a title that has lost its subject has lost the +reason to rank; and a shape is only shortened when the shortened form still fits, +so two pages never collapse onto one title. + +### 2. Browse hubs are generated from the same metadata + +`src/src/lib/hubs.ts` derives: + +- `/topics/<topic>/` from GitHub repository topics; +- `/categories/<category>/` from the catalogue's `category` vocabulary; +- `/packages/` from every declared package. + +Every hub lists the real projects (status, description, documentation link) and +the documentation pages behind them, so the page has content of its own. A hub is +**only published when it indexes at least two projects** (`MIN_HUB_PROJECTS`): +one-link hubs are the doorway pages search engines devalue, and a topic only one +project carries is better served by that project's page. + +Hubs are ordinary Astro pages, so they enter the sitemap, `discover.json`, +`robots.txt` and the IndexNow diff through the existing discovery model +(ADR 0007) with no extra registration — but they are a **new URL family**, hence +this ADR. + +### 3. `og:type` is never set globally + +The site's own pages set `website` themselves in `SiteLayout`; documentation pages +keep Starlight's `article`. A global value in the config silently wins over both. + +### 4. Structured data describes the entity, not the template + +- Documentation pages: `TechArticle` (with `keywords` from the repository topics, + `articleSection` from the folder trail, `dateModified` from `lastReviewed`, + `mainEntityOfPage`) plus a `BreadcrumbList` that mirrors the visible structure. +- Project pages: `SoftwareSourceCode` **and** `SoftwareApplication` (free offer, + `downloadUrl`, `softwareRequirements` from the declared target frameworks) plus + the existing `BreadcrumbList`. Assertions are made only when true: a project + with no NuGet package is not given `programmingLanguage: C#`. +- Hubs: `CollectionPage` + `ItemList` + `BreadcrumbList`. + +### 5. Internal anchor text names its destination + +A use case links to a documentation page by name ("Read Union design"), and a +topic chip becomes a link to its hub whenever that hub exists. The set of tags +with hubs is computed once (`getHubs()`), so a chip can never point at a 404. + +### 6. `lastmod` sources are derived, not listed + +`PAGE_SOURCES` was a hand-kept map of six routes. Any page not in it — the +`/examples/astroc4/` demo page, and every page added since — silently fell back to +the release cache's retrieval time, which is the build time, which is the one +signal ADR 0007 forbids. The index is now built by walking `src/src/pages` +(workspace-root-relative, so keys still match `git log`), with `[param]` routes +matched by pattern. + +### 7. The rules are enforced against the built output + +`bun run check:seo` (`src/scripts/check-seo.ts`) runs over `dist/` and fails on +structural violations: not exactly one `<h1>`, a missing or duplicated `<title>`, +a missing description, a canonical that is not self-referencing, `noindex` on an +indexable URL, a documentation title that does not name its project, invalid or +missing JSON-LD. Title and description *lengths* are advisories only, printed and +never fatal — a rule that fails on taste is a rule that gets weakened (ADR 0001). + +### 8. Off-site signals are a repository responsibility, recorded in the skills + +`purview.dev` has no followed inbound links except the GitHub **Website** field of +each repository, and those point at `/projects/<id>/` only. NuGet's project URL +and README links are all `rel="nofollow"`. The consumer skills +(`purview-site-integration`, `purview-site-docs`) therefore require a product +repository to link its published pages, and the assessment skill reports when it +does not — the one part of SEO this repository cannot do for itself. + +## Consequences + +- Titles change once; previously indexed pages will be re-crawled under their new + titles. Canonicals are unchanged, so no URL moves. +- The sitemap gains a page per shared topic and category, plus `/packages/`. + `discovery:validate` and `check-links` cover them without modification because + they come from the same discovery model. +- A project onboarding now also creates hub memberships; a project whose topics + are poor (fewer than two shared) contributes to no topic hub, which makes the + existing "set real GitHub topics" intake question more consequential than it was. +- `check:seo` joins `just validate`, so a page that loses its title, its canonical + or its structured data fails the build rather than the ranking. + diff --git a/docs/discovery.md b/docs/discovery.md index f61c1ec..eb1e37b 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -44,7 +44,11 @@ under `docsChannels` (schemaVersion 2). ### Sitemap partitioning - **pages.xml** — hand-authored pages (`/`, `/about/`, `/docs/`, `/projects/`, - `/releases/`, `/use-cases/`). + `/releases/`, `/use-cases/`) and the generated browse hubs + (`/topics/`, `/topics/<topic>/`, `/categories/`, `/categories/<category>/`, + `/packages/`). See ADR 0015: the hubs are ordinary Astro pages derived from the + catalogue's GitHub topics and category, so they enter the sitemap through the + same model as every other page. - **projects.xml** — every project landing page (`/projects/<id>/`) and all of its aggregated documentation (`/docs/<id>/…`), derived from the catalogue and the docs manifest. @@ -53,6 +57,27 @@ under `docsChannels` (schemaVersion 2). Error pages (`404`, `500`), non-canonical aliases and non-indexable pages are excluded. +### Titles, canonicals and structured data + +Being *findable* is not only about being crawled. ADR 0015 derives every +`<title>` and meta description from the catalogue (`src/src/lib/seo.ts`, composed +into the page by the `Head` override), publishes the browse hubs above, and keeps +the page's own title as its visible H1 while the search-result title names the +product. Every derived title is budgeted to the ~70 characters a result shows, +with the folder trail and the word "documentation" dropped before anything that +identifies the page. That is enforced against the built output +by `bun run check:seo` (`src/scripts/check-seo.ts`), which is part of +`just validate`: one `<h1>` per page, unique non-empty titles, self-referencing +canonicals, a documentation title that names its project, and valid JSON-LD. +Length guidance is reported as an advisory and never fails the build. + +The one signal this repository cannot create for itself is an inbound link from +another site: NuGet renders its project-URL and README links `rel="nofollow"`, so +the followed links come from each product repository's README and GitHub +**Website** field. The consumer skills (`purview-site-integration`, +`purview-site-docs`) require them, and `purview-site-assessment` reports when one +is missing. + ### Meaningful `lastmod` `lastmod` is **never** the build time. Each resource is dated from the source @@ -195,6 +220,8 @@ Automated (nothing to do per deploy): - [x] IndexNow key file written from the secret by the deploy workflow - [x] IndexNow notifies changed URLs after a successful deploy - [x] `discovery:validate` enforced in CI +- [x] `check:seo` enforced in CI (titles, canonicals, one H1, project-named docs + titles, valid JSON-LD) — ADR 0015 One-time (operator): diff --git a/justfile b/justfile index c802c3f..cc331bf 100644 --- a/justfile +++ b/justfile @@ -87,6 +87,10 @@ check-generated: check-projects: bun run check:projects +# Validate search-engine metadata in the built site (titles, canonicals, headings, structured data). +check-seo: + bun run check:seo + # Apply the guard's auto-fixes to the project records (dry run; pass --write to apply). fix-projects *ARGS: bun run fix:projects {{ARGS}} @@ -124,5 +128,5 @@ clean: bun run clean # Authoritative validation: run everything needed to prove the site is safe to merge. -validate: format-check lint typecheck test check-assets check-projects build discovery-validate check-links check-generated test-dist +validate: format-check lint typecheck test check-assets check-projects build discovery-validate check-seo check-links check-generated test-dist @echo "Validation passed." diff --git a/package.json b/package.json index 1711f00..fc55d13 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "purview-dev", - "version": "0.10.0", + "version": "0.11.0", "private": true, "description": "Purview-Dev public website and unified documentation portal (workspace root).", "license": "MIT", @@ -14,7 +14,8 @@ "check:generated": "bun run --cwd src check:generated", "check:links": "bun run --cwd src check:links", "check:projects": "bun run --cwd src check:projects", - "ci:build": "bun run data:sync && bun run typecheck && bun run check:assets && bun run check:projects && bun run build && bun run discovery:validate && bun run check:links && bun run check:generated && bun run test:dist", + "check:seo": "bun run --cwd src check:seo", + "ci:build": "bun run data:sync && bun run typecheck && bun run check:assets && bun run check:projects && bun run build && bun run discovery:validate && bun run check:seo && bun run check:links && bun run check:generated && bun run test:dist", "clean": "bun run --cwd src clean", "data:sync": "bun run --cwd src data:sync", "dev": "bun run --cwd src dev", diff --git a/skills/add-project-intake/SKILL.md b/skills/add-project-intake/SKILL.md index 4f676f5..f834a41 100644 --- a/skills/add-project-intake/SKILL.md +++ b/skills/add-project-intake/SKILL.md @@ -103,7 +103,7 @@ resolve to a real page under `/docs/<id>/` (see `use-case-authoring`). | # | Question | Decides | | --- | --- | --- | -| 23 | Repository topics are missing or poor — they are the site's tag chips. May I set them? | tags (`check-projects` **fails** on no topics) | +| 23 | Repository topics are missing or poor — they are the site's tag chips and the `/topics/` hubs a project appears in. May I set them? | tags (`check-projects` **fails** on no topics); browse hubs (ADR 0015) | | 24 | The description is thin — it backs the `shortDescription` fallback and social metadata. May I improve it? | `shortDescription` fallback, `og:` metadata | | 25 | Is there a schema or artefact worth mirroring to a stable `purview.dev` URL (an `assets:` entry), or is it already published elsewhere? | `assets` | diff --git a/skills/github-repo-metadata/SKILL.md b/skills/github-repo-metadata/SKILL.md index c346bc1..3716f37 100644 --- a/skills/github-repo-metadata/SKILL.md +++ b/skills/github-repo-metadata/SKILL.md @@ -26,6 +26,7 @@ Everything else in the table below is build-time. | Site surface | Source | Notes | | --- | --- | --- | | Tag chips (cards, docs portal, docs-page front matter `tags`) | GitHub **topics** | `projectRepoEnrichment()` in `src/src/lib/releases/repo.ts` | +| The `/topics/<topic>/` browse hub a chip links to | GitHub **topics** | A topic shared by two or more projects gets a hub page (ADR 0015); a topic only one project carries links nowhere, and one hub's worth of links is lost | | `shortDescription` fallback | GitHub **description** | Used only when the manifest value is empty | | "supplemental" description on the project page | GitHub description | Shown when it differs from the manifest description | | Successor/archived messaging | GitHub **archived** flag + `status`/`supersededBy` | | @@ -72,6 +73,9 @@ Discussions on an organisation repository requires organisation permission; repo searches behave predictably. - Topics are the **only** way tags reach the site. There is no `tags` field in a catalogue record — do not add one. +- Spell a shared concept the standard way and only the standard way: `csharp`, not `c-sharp`. The + site groups the two spellings into one `/topics/csharp/` hub, but a topic nobody else uses gets no + hub at all, so a project's topics are also how it joins the site's browse surfaces (ADR 0015). ## Stability signals to check against `status` diff --git a/skills/purview-site-assessment/references/rules.md b/skills/purview-site-assessment/references/rules.md index 245e585..2638c36 100644 --- a/skills/purview-site-assessment/references/rules.md +++ b/skills/purview-site-assessment/references/rules.md @@ -55,6 +55,18 @@ The text-fence classifier skips folder trees (`├──`, `└──`), which a RED-004 reads the last 300 commits that touched the docs folder. A page that existed only between two site builds was never published; ignore those. +## Search visibility + +| Rule | Severity | Finding | Fix | +| -- | -- | -- | -- | +| SEO-001 | warning | the README does not link `purview.dev`, so the site has no followed inbound link from this repository | link the published documentation (`https://purview.dev/docs/<id>/`) near the top of the README, with link text a reader would search with | +| SEO-002 | info | the repository has no Website/Homepage field (checked by hand with `gh api repos/<owner>/<repo> --jq .homepage`) | set it to `https://purview.dev/projects/<id>/`; the published pages already link back with their own URL | +| SEO-003 | info | a docs page whose first paragraph does not name the technology it documents | make the first sentence answer "what does this page cover?" — the site uses it as the meta description (ADR 0015) | + +NuGet renders the project URL and every README link `rel="nofollow"`, and the +GitHub Website field is followed, so SEO-001/SEO-002 are the only inbound links +the site can earn from a repository. Not a formatting nicety. + ## Catalogue (with `--catalogue`) | Rule | Severity | Finding | Fix | diff --git a/skills/purview-site-assessment/scripts/assess.mjs b/skills/purview-site-assessment/scripts/assess.mjs index 644c8b5..15010fa 100644 --- a/skills/purview-site-assessment/scripts/assess.mjs +++ b/skills/purview-site-assessment/scripts/assess.mjs @@ -335,6 +335,30 @@ for (const site of ['mkdocs.yml', 'mkdocs.yaml', 'docs/mkdocs.yml', 'docs/wiki/m } } +// --------------------------------------------------------------------------- +// Search visibility +// --------------------------------------------------------------------------- + +// purview.dev's only *followed* inbound links come from this repository: NuGet +// renders the project URL and README links `rel="nofollow"`, and the GitHub +// Website field is a followed link into the catalogue page. Without one of them +// the published page cannot rank for the topic it documents, however good it is +// (ADR 0015). +if (readmePath) { + const readmeText = read(readmePath); + const relativeReadme = toPosix(relative(root, readmePath)); + if (!/purview\.dev/.test(readmeText)) { + report( + 'SEO-001', + 'warning', + relativeReadme, + undefined, + 'The README does not link the published site, so purview.dev has no followed inbound link from this repository.', + 'Link the published documentation (https://purview.dev/docs/<id>/) near the top, with link text a reader would search with ("Union design", "Installation guide").', + ); + } +} + // --------------------------------------------------------------------------- // Documentation // --------------------------------------------------------------------------- diff --git a/skills/purview-site-docs/SKILL.md b/skills/purview-site-docs/SKILL.md index 9e916d3..7f7ff33 100644 --- a/skills/purview-site-docs/SKILL.md +++ b/skills/purview-site-docs/SKILL.md @@ -33,9 +33,25 @@ The site's catalogue entry for your project (in `purview-dev/purview-dev`, | 9 | **Diagrams are never ASCII art.** A diagram is a LikeC4 model paired with a Mermaid fence (below). | ASCII art is unreadable on a phone, unsearchable, and drifts silently. | | 10 | Moving or renaming a page adds a line to `_redirects.yml` in the same commit. | The old URL is in bookmarks, search results and other repositories. | | 11 | `_Sidebar.md` lists every page once, grouped by section, in reading order. | The site orders pages by it; a page missing from it has no place in the navigation. | +| 12 | **The first paragraph names the technology in the words a reader would search with**, and the H1 stays the page's own name. | The first paragraph becomes the meta description and the H1 becomes the page title; a page that never says "C# union types" cannot be found by someone searching for exactly that. The site builds the search-result title (`Union design — Unions documentation`), so the H1 does not need the project name in it. | Full layout rules, a worked tree and what the site rewrites: [references/layout.md](references/layout.md). +## Where the published copy lives + +`https://purview.dev/docs/<project-id>/` is the canonical home of these pages; the same Markdown on +GitHub is a mirror, not a second edition. Link the published URL from the repository's README (rule 5 +of `purview-site-integration`) and keep prose in one place: a page duplicated in the README competes +with the site for the same query, on a domain that wins. + +The site titles and describes each page for search from the catalogue and the page itself +(ADR 0015). Two consequences for writing here: + +- the H1 is the page's name, and a folder is a section: `schemas/Custom-Rules.md` is published as + `/docs/<id>/schemas/custom-rules/` and titled `Schemas · Custom rules — <Project> documentation`; +- the first paragraph is the description, trimmed to about 160 characters at a sentence boundary, so + make its first sentence the answer to "what does this page cover?". + ## Hierarchy: the default shape ```text diff --git a/skills/purview-site-integration/SKILL.md b/skills/purview-site-integration/SKILL.md index 24cd40a..89a9abb 100644 --- a/skills/purview-site-integration/SKILL.md +++ b/skills/purview-site-integration/SKILL.md @@ -36,6 +36,7 @@ So integration has two halves: make this repository **readable** (this skill and | Build badge | the repository's GitHub Actions | A workflow that runs on the default branch | | Discussions link | repository settings | Enable Discussions if you want readers to ask there | | Star count | GitHub | — | +| **Inbound links to the published pages** | the repository's `README.md` and its GitHub **Website** field | Link `https://purview.dev/docs/<id>/` from the README (and set the Website field to `https://purview.dev/projects/<id>/`). This is not polish: NuGet renders the project URL and every README link `rel="nofollow"`, so the README and the Website field are the site's only *followed* inbound links — without them a page cannot rank for its own topic, however good it is | The default branch must be `main` unless the entry says otherwise; the docs, the edit links and the "last reviewed" dates all follow it. @@ -58,10 +59,16 @@ The default branch must be `main` unless the entry says otherwise; the docs, the 5. **README** — the GitHub front door: what it is, install, a minimal example, a link into the docs. It points into the docs rather than duplicating them (a `readme`-sourced project is the exception: the README *is* the docs). -6. **The entry** — collect what [references/catalogue-contract.md](references/catalogue-contract.md) +6. **Publish the pointer** — the README links its published documentation + (`https://purview.dev/docs/<id>/`) and the repository's Website field is + `https://purview.dev/projects/<id>/`. GitHub README links are followed and NuGet's + are not, so this is where the site's inbound links come from. Write the link as the + reader would say it ("Installation guide", "Union design") rather than "click here": + the link text is part of what the destination ranks for. +7. **The entry** — collect what [references/catalogue-contract.md](references/catalogue-contract.md) asks for, and hand it to the site maintainers (an issue or pull request on `purview-dev/purview-dev`). The site's own agents onboard projects from that information. -7. **Assess** — run the `purview-site-assessment` skill and fix every error before asking for the +8. **Assess** — run the `purview-site-assessment` skill and fix every error before asking for the entry. ## Live examples and diagrams on the project page diff --git a/src/astro.config.ts b/src/astro.config.ts index 9f01dcb..5cff86a 100644 --- a/src/astro.config.ts +++ b/src/astro.config.ts @@ -101,10 +101,10 @@ const HEAD = [ tag: 'meta' as const, attrs: { name: 'theme-color', content: BRAND.inkLight, media: '(prefers-color-scheme: dark)' }, }, - { - tag: 'meta' as const, - attrs: { property: 'og:type', content: 'website' }, - }, + // `og:type` is deliberately NOT set here. Starlight emits `article` for a + // documentation page; a global `website` in the config overrides that on every + // one of the aggregated documentation pages. The site's own pages set their own + // `og:type` (see `SiteLayout.astro`). { tag: 'meta' as const, attrs: { property: 'og:site_name', content: SITE.fullName }, diff --git a/src/package.json b/src/package.json index d7887f6..69bad8d 100644 --- a/src/package.json +++ b/src/package.json @@ -11,6 +11,7 @@ "check:generated": "bun run scripts/check-generated.ts", "check:links": "bun run scripts/check-links.ts", "check:projects": "bun run scripts/check-projects.ts", + "check:seo": "bun run scripts/check-seo.ts", "clean": "bun run scripts/clean.ts", "data:sync": "bun run scripts/data-sync.ts", "dev": "astro dev", diff --git a/src/scripts/check-seo.ts b/src/scripts/check-seo.ts new file mode 100644 index 0000000..4ed44d6 --- /dev/null +++ b/src/scripts/check-seo.ts @@ -0,0 +1,297 @@ +import type { DiscoverableResource } from '../src/lib/discovery/types'; + +import { existsSync, readFileSync } from 'node:fs'; +import { join, resolve } from 'node:path'; + +import { DISCOVER_JSON_PATH } from '../src/lib/discovery/urls'; +import { loadProjects } from '../src/lib/manifest/load'; +import { productName } from '../src/lib/seo'; + +/** + * `bun run check:seo` + * + * The SEO invariants the *built site* must keep, checked against the real output + * rather than against the code that produced it: + * + * - every indexable URL has exactly one `<h1>`, a self-referencing canonical, a + * non-empty `<title>` and a non-empty `<meta name="description">`; + * - `<title>`s are unique, and every aggregated documentation page names its + * project (a docs title that omits the product is unreachable from a search + * for that product — see `lib/seo`); + * - every JSON-LD block on a documentation or project page parses; + * - an indexable URL never carries `noindex`. + * + * Length guidance is reported as an *advisory*, never a failure: a title of 80 + * characters is a judgement call, and a check that fails on taste gets weakened + * (ADR 0001). A missing title is not a judgement call. + */ + +export interface SeoIssue { + url: string; + message: string; +} + +export interface SeoReport { + errors: SeoIssue[]; + advisories: SeoIssue[]; + /** Indexable URLs examined. */ + pages: number; +} + +/** Advisory ceiling: search engines truncate around here. */ +const TITLE_ADVISORY = 70; +const DESCRIPTION_ADVISORY_MIN = 70; +const DESCRIPTION_ADVISORY_MAX = 175; + +/** How many advisories to print before summarising the rest. */ +const ADVISORY_SAMPLE = 10; + +const TITLE_PATTERN = /<title[^>]*>([\s\S]*?)<\/title>/i; +const H1_PATTERN = /<h1[\s>]/gi; +const CANONICAL_PATTERN = /<link[^>]+rel=["']canonical["'][^>]*>/i; +const HREF_PATTERN = /href=["']([^"']+)["']/i; +const JSONLD_PATTERN = /<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi; + +/** Decode the entities the site's own templates emit in titles. */ +export function decodeEntities(value: string): string { + return value + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, "'") + .replace(/ /g, ' ') + .trim(); +} + +export function extractTitle(html: string): string | null { + const match = TITLE_PATTERN.exec(html); + return match?.[1] === undefined ? null : decodeEntities(match[1]); +} + +/** + * Read one attribute from a tag, honouring the quote that delimits it. + * + * A naive `[^"']+` stops at an apostrophe inside the value, which silently + * truncates any description containing one ("Purview's …" became "Purview"), so + * the delimiter is matched exactly. + */ +export function readAttribute(tag: string, name: string): string | undefined { + const pattern = new RegExp(`${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, 'i'); + const match = pattern.exec(tag); + return match?.[1] ?? match?.[2]; +} + +/** All `<meta>` tags with the given attribute, as `attrValue -> content` maps. */ +export function extractMeta(html: string, attribute: 'name' | 'property'): Map<string, string> { + const result = new Map<string, string>(); + for (const match of html.matchAll(/<meta\b[^>]*>/gi)) { + const tag = match[0]; + const key = readAttribute(tag, attribute)?.toLowerCase(); + const content = readAttribute(tag, 'content'); + if (key !== undefined && key !== '' && content !== undefined && !result.has(key)) { + result.set(key, decodeEntities(content)); + } + } + return result; +} + +export function extractCanonical(html: string): string | null { + const tag = CANONICAL_PATTERN.exec(html)?.[0]; + if (tag === undefined) { + return null; + } + return HREF_PATTERN.exec(tag)?.[1] ?? null; +} + +export function countH1(html: string): number { + return [...html.matchAll(H1_PATTERN)].length; +} + +/** Parsed JSON-LD payloads; `null` marks a block that is not valid JSON. */ +export function extractJsonLd(html: string): (unknown | null)[] { + const blocks: (unknown | null)[] = []; + for (const match of html.matchAll(JSONLD_PATTERN)) { + try { + blocks.push(JSON.parse(match[1] ?? '')); + } catch { + blocks.push(null); + } + } + return blocks; +} + +/** The `dist` file a canonical site path is published as. */ +export function distFileForPath(dist: string, pathname: string): string { + const clean = pathname.replace(/^\//, '').replace(/\/$/, ''); + return clean === '' ? join(dist, 'index.html') : join(dist, ...clean.split('/'), 'index.html'); +} + +/** + * Every documented project's URL prefix, with the names a docs page title may + * use to identify it: the catalogue display name and the product (package) name. + */ +function documentationTargets(): Map<string, string[]> { + const targets = new Map<string, string[]>(); + for (const project of loadProjects()) { + if (!project.docs || project.status === 'archived') { + continue; + } + const names = [project.name, productName(project)].filter((name) => name !== ''); + targets.set(`/docs/${project.id}/`, names); + } + return targets; +} + +export function checkSeo(dist = resolve('dist')): SeoReport { + const errors: SeoIssue[] = []; + const advisories: SeoIssue[] = []; + const discoverFile = join(dist, DISCOVER_JSON_PATH.replace(/^\//, '')); + if (!existsSync(discoverFile)) { + return { + errors: [{ url: DISCOVER_JSON_PATH, message: 'discover.json is missing; run `just build`.' }], + advisories: [], + pages: 0, + }; + } + + let resources: DiscoverableResource[] = []; + try { + const manifest = JSON.parse(readFileSync(discoverFile, 'utf8')) as { + resources?: DiscoverableResource[]; + }; + resources = manifest.resources ?? []; + } catch { + return { + errors: [{ url: DISCOVER_JSON_PATH, message: 'discover.json is not valid JSON.' }], + advisories: [], + pages: 0, + }; + } + + // The machine-readable bundles are text files with no head of their own. + const indexable = resources.filter( + (resource) => resource.indexable && !new URL(resource.url).pathname.endsWith('.txt'), + ); + const docsPrefixes = documentationTargets(); + const titles = new Map<string, string>(); + let pages = 0; + + for (const resource of indexable) { + const pathname = new URL(resource.url).pathname; + const file = distFileForPath(dist, pathname); + if (!existsSync(file)) { + errors.push({ url: resource.url, message: 'indexable URL has no built page.' }); + continue; + } + pages += 1; + const html = readFileSync(file, 'utf8'); + const title = extractTitle(html); + const description = extractMeta(html, 'name').get('description') ?? ''; + const canonical = extractCanonical(html); + const h1 = countH1(html); + + if (h1 !== 1) { + errors.push({ url: resource.url, message: `expected exactly one <h1>, found ${h1}.` }); + } + if (title === null || title === '') { + errors.push({ url: resource.url, message: 'the page has no <title>.' }); + } else { + const existing = titles.get(title); + if (existing !== undefined) { + errors.push({ + url: resource.url, + message: `duplicate <title> — also used by ${existing}.`, + }); + } else { + titles.set(title, resource.url); + } + if (title.length > TITLE_ADVISORY) { + advisories.push({ + url: resource.url, + message: `title is ${title.length} characters (search engines truncate around ${TITLE_ADVISORY}).`, + }); + } + } + if (description === '') { + errors.push({ url: resource.url, message: 'the page has no <meta name="description">.' }); + } else if ( + description.length < DESCRIPTION_ADVISORY_MIN || + description.length > DESCRIPTION_ADVISORY_MAX + ) { + advisories.push({ + url: resource.url, + message: `description is ${description.length} characters (aim for ${DESCRIPTION_ADVISORY_MIN}-${DESCRIPTION_ADVISORY_MAX}).`, + }); + } + if (canonical === null) { + errors.push({ url: resource.url, message: 'the page has no canonical link.' }); + } else if (canonical !== resource.url) { + errors.push({ url: resource.url, message: `canonical points elsewhere: ${canonical}.` }); + } + if (extractMeta(html, 'name').get('robots')?.includes('noindex') === true) { + errors.push({ url: resource.url, message: 'an indexable URL is marked noindex.' }); + } + + // A documentation page must say which project it documents. + for (const [prefix, names] of docsPrefixes) { + if (!pathname.startsWith(prefix) || names.length === 0) { + continue; + } + if (title !== null && !names.some((name) => title.includes(name))) { + errors.push({ + url: resource.url, + message: `documentation title does not name the project (expected "${names.join('" or "')}"): ${title}`, + }); + } + break; + } + + const isProjectOrDocs = pathname.startsWith('/docs/') || pathname.startsWith('/projects/'); + const jsonLd = extractJsonLd(html); + jsonLd.forEach((block, index) => { + if (block === null) { + errors.push({ + url: resource.url, + message: `JSON-LD block ${index + 1} is not valid JSON.`, + }); + } + }); + if (isProjectOrDocs && jsonLd.length === 0) { + errors.push({ url: resource.url, message: 'no JSON-LD structured data on the page.' }); + } + } + + return { errors, advisories, pages }; +} + +if (import.meta.main) { + console.log('Checking search-engine metadata in the built site...'); + const { errors, advisories, pages } = checkSeo(resolve('dist')); + for (const error of errors) { + console.error(` ✗ ${error.url}: ${error.message}`); + } + if (advisories.length > 0) { + // Advisories are guidance, not failures: they are summarised with a sample so + // a genuine error is never buried under a hundred length notes. + const shown = advisories.slice(0, ADVISORY_SAMPLE); + for (const advisory of shown) { + console.warn(` ⚠ ${advisory.url}: ${advisory.message}`); + } + const hidden = advisories.length - shown.length; + const titleNotes = advisories.filter((note) => note.message.startsWith('title')).length; + const descriptionNotes = advisories.length - titleNotes; + console.warn( + ` ⚠ ${advisories.length} advisory note(s): ${titleNotes} title length, ` + + `${descriptionNotes} description length` + + (hidden > 0 ? ` — showing the first ${shown.length}` : ''), + ); + } + if (errors.length > 0) { + console.error(`\nSEO check failed with ${errors.length} issue(s) across ${pages} page(s).`); + process.exit(1); + } + console.log( + `SEO check passed: ${pages} indexable page(s), ${advisories.length} advisory note(s).`, + ); +} diff --git a/src/src/components/HubBody.astro b/src/src/components/HubBody.astro new file mode 100644 index 0000000..c620d0e --- /dev/null +++ b/src/src/components/HubBody.astro @@ -0,0 +1,75 @@ +--- +import InlineProse from '~/components/InlineProse.astro'; +import StatusBadge from '~/components/StatusBadge.astro'; +import type { Hub } from '~/lib/hubs'; +import { withBase } from '~/lib/urls'; + +/** + * The body of a topic or category hub. + * + * A hub earns its place by listing real things, not by repeating a keyword: the + * projects tagged with the topic (with their status, description and a link into + * their documentation) followed by the documentation pages those projects + * publish. Both lists are derived from the catalogue and the docs manifest. + */ +interface Props { + hub: Hub; + kind: 'topic' | 'category'; +} + +const { hub, kind } = Astro.props; +const subject = kind === 'topic' ? `tagged ${hub.label}` : `in ${hub.label}`; +--- + +<section class="mt-10"> + <h2 class="text-2xl font-bold tracking-tight md:text-3xl">Projects</h2> + <div class="mt-6 grid gap-5 sm:grid-cols-2 lg:grid-cols-3"> + { + hub.projects.map((project) => ( + <div class="pv-card flex flex-col gap-3 p-5"> + <div class="flex items-start justify-between gap-3"> + <h3 class="min-w-0 text-lg font-semibold leading-snug"> + <a href={withBase(project.url)} class="pv-link"> + {project.name} + </a> + </h3> + <StatusBadge status={project.status} class="shrink-0" /> + </div> + <p class="text-sm text-muted"> + <InlineProse text={project.description} /> + </p> + <div class="mt-auto flex flex-wrap items-center gap-2 pt-2"> + <span class="pv-chip">{project.category}</span> + {project.docsUrl && ( + <a href={withBase(project.docsUrl)} class="pv-chip no-underline"> + {project.docsPageCount} documentation page + {project.docsPageCount === 1 ? '' : 's'} + </a> + )} + </div> + </div> + )) + } + </div> +</section> + +{ + hub.pages.length > 0 && ( + <section class="mt-12"> + <h2 class="text-2xl font-bold tracking-tight md:text-3xl">Documentation</h2> + <p class="mt-2 max-w-2xl text-muted"> + Every page below belongs to a project {subject}. Follow one to read the guide, reference or + examples behind the topic. + </p> + <ul class="mt-6 grid list-none gap-x-8 gap-y-2 sm:grid-cols-2 lg:grid-cols-3"> + {hub.pages.map((page) => ( + <li> + <a href={withBase(page.url)} class="pv-link"> + {page.title} <span class="text-muted">— {page.projectName}</span> + </a> + </li> + ))} + </ul> + </section> + ) +} diff --git a/src/src/components/SiteFooter.astro b/src/src/components/SiteFooter.astro index d9930c5..2e60df4 100644 --- a/src/src/components/SiteFooter.astro +++ b/src/src/components/SiteFooter.astro @@ -45,6 +45,18 @@ const releasesUrl = `${SITE.githubUrl}/${OWNER}.github.io/releases`; </li> )) } + {/* The browse surfaces: server-rendered indexes of the catalogue that a + reader (and a crawler) can follow without using the client-side + filter on /projects/. */} + <li> + <a href={withBase('/topics/')} class="pv-link">Topics</a> + </li> + <li> + <a href={withBase('/categories/')} class="pv-link">Categories</a> + </li> + <li> + <a href={withBase('/packages/')} class="pv-link">Packages</a> + </li> </ul> </nav> diff --git a/src/src/components/UseCaseCard.astro b/src/src/components/UseCaseCard.astro index ff7f874..9eedba6 100644 --- a/src/src/components/UseCaseCard.astro +++ b/src/src/components/UseCaseCard.astro @@ -12,9 +12,15 @@ interface Props { docsBase: string | null; /** Hide the owning project chip when the card is already scoped to that project. */ showProject?: boolean; + /** + * Title of the documentation page the guide link opens. Naming the destination + * is what makes the link text meaningful to a reader (and to a crawler): the + * same card on a different page then says which guide it leads to. + */ + docsLabel?: string; } -const { useCase, projectName, projectId, docsBase, showProject = true } = Astro.props; +const { useCase, projectName, projectId, docsBase, showProject = true, docsLabel } = Astro.props; const audienceLabel = AUDIENCE_LABELS[useCase.audience]; const docsLink = docsBase && useCase.docsPage ? `${docsBase}${useCase.docsPage}/` : (docsBase ?? null); @@ -49,7 +55,7 @@ const docsLink = { docsLink && ( <a href={docsLink} class="pv-link mt-auto text-sm" data-use-case-project={projectId}> - Read the guide → + Read {docsLabel ?? 'the guide'} → </a> ) } diff --git a/src/src/components/starlight/Head.astro b/src/src/components/starlight/Head.astro index ad23904..e4f482c 100644 --- a/src/src/components/starlight/Head.astro +++ b/src/src/components/starlight/Head.astro @@ -1,26 +1,32 @@ --- import DefaultHead from '@astrojs/starlight/components/Head.astro'; import { readDocsManifest } from '~/lib/docs/aggregate'; +import { CHANNEL_LABELS, channelBasePath, channelDisplayLabel } from '~/lib/docs/channels'; +import { docSectionTrail } from '~/lib/docs/sidebar'; import { projectChannelLlmsFullUrl } from '~/lib/discovery/urls'; +import { getProjects } from '~/lib/manifest/load'; +import { docsIndexTitle, docsPageTitle } from '~/lib/seo'; import { SITE } from '~/lib/site'; import { absoluteUrl } from '~/lib/urls'; // Documentation pages are aggregated from the product repositories. Expose the // machine-readable bundle of the version the page came from as an alternate -// representation and a `TechArticle` JSON-LD block. A project can publish more -// than one version (ADR 0009), and each version has its own bundle, so the link -// follows the page's channel rather than the project's default. Only accurate -// values are emitted; the canonical HTML page remains the primary content. +// representation and describe the page for search engines. A project can publish +// more than one version (ADR 0009), and each version has its own bundle, so the +// link follows the page's channel rather than the project's default. const data = Astro.locals.starlightRoute?.entry?.data; const sourceProject = typeof data?.sourceProject === 'string' ? data.sourceProject : undefined; const hasMachineReadable = sourceProject !== undefined && data?.status !== 'archived'; const docsChannel = typeof data?.docsChannel === 'string' ? data.docsChannel : undefined; +const docsManifest = sourceProject === undefined ? null : readDocsManifest(); +const projectEntry = docsManifest?.projects.find((entry) => entry.projectId === sourceProject); const channel = - sourceProject === undefined - ? undefined - : readDocsManifest() - ?.projects.find((project) => project.projectId === sourceProject) - ?.channels.find((candidate) => candidate.id === docsChannel); + projectEntry?.channels.find((candidate) => candidate.id === docsChannel) ?? + projectEntry?.channels.find((candidate) => candidate.default); +const page = channel?.pages.find((candidate) => candidate.sourcePath === data?.sourcePath); +// The folder a page lives in is part of its URL (ADR 0011), so the breadcrumb +// names the sections above the page, not only the project. +const sectionTrail = page ? docSectionTrail(page.slug) : []; const fullUrl = sourceProject === undefined ? null @@ -37,18 +43,102 @@ const alternateLinks = : []; const canonical = absoluteUrl(Astro.url.pathname === '' ? '/' : Astro.url.pathname); +// The search-result title is composed here rather than in the aggregated front +// matter: the docs mirror is a mirror of the documentation, not of this site's +// metadata, and the title needs the catalogue and the manifest, both of which are +// in hand at render time (ADR 0015). Starlight's own title is replaced, not +// appended to, so no page can end up with two of them. +const head = Astro.locals.starlightRoute?.head; +const titleEntry = head?.find((entry) => entry.tag === 'title'); +if (titleEntry !== undefined && sourceProject !== undefined) { + const project = getProjects().find((candidate) => candidate.id === sourceProject); + const indexPage = (page?.slug ?? 'index') === 'index'; + const qualifier = + channel && !channel.default ? + indexPage ? channelDisplayLabel(channel) : CHANNEL_LABELS[channel.id] + : undefined; + const brand = SITE.fullName; + titleEntry.content = + indexPage ? + docsIndexTitle(project ?? { name: data?.projectName ?? sourceProject, shortDescription: '', category: '' }, { qualifier, brand }) + : docsPageTitle({ + pageTitle: data?.title ?? sourceProject, + projectName: data?.projectName ?? sourceProject, + sectionTrail, + qualifier, + brand, + }); +} else if (titleEntry?.content && !titleEntry.content.includes(SITE.fullName)) { + titleEntry.content = `${titleEntry.content} | ${SITE.fullName}`; +} +const projectDocsUrl = + sourceProject === undefined + ? null + : channel + ? absoluteUrl(channelBasePath(sourceProject, channel.id, channel.default)) + : absoluteUrl(`/docs/${sourceProject}/`); +const keywords = Array.isArray(data?.tags) ? (data.tags as string[]) : []; const structuredData = data ? { '@context': 'https://schema.org', - '@type': 'TechArticle', - headline: data.title, - ...(typeof data.description === 'string' ? { description: data.description } : {}), - url: canonical, - ...(typeof data.lastReviewed === 'string' ? { dateModified: data.lastReviewed } : {}), - inLanguage: 'en', - isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, - publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + '@graph': [ + { + '@type': 'TechArticle', + headline: data.title, + ...(typeof data.description === 'string' ? { description: data.description } : {}), + url: canonical, + mainEntityOfPage: canonical, + ...(typeof data.lastReviewed === 'string' ? { dateModified: data.lastReviewed } : {}), + inLanguage: 'en', + ...(keywords.length > 0 ? { keywords: keywords.join(', ') } : {}), + ...(sectionTrail.length > 0 ? { articleSection: sectionTrail.join(' › ') } : {}), + author: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + isPartOf: { + '@type': projectDocsUrl ? 'CollectionPage' : 'WebSite', + name: projectDocsUrl + ? `${data.projectName ?? sourceProject} documentation` + : SITE.fullName, + url: projectDocsUrl ?? SITE.url, + }, + }, + { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', item: absoluteUrl('/') }, + { + '@type': 'ListItem', + position: 2, + name: 'Documentation', + item: absoluteUrl('/docs/'), + }, + ...(projectDocsUrl ? + [ + { + '@type': 'ListItem', + position: 3, + name: data.projectName ?? sourceProject, + item: projectDocsUrl, + }, + ] + : []), + // A folder is a place in the tree, not a page (ADR 0011), so a + // section is named without a URL rather than pointed at nothing. + ...sectionTrail.map((section, index) => ({ + '@type': 'ListItem', + position: 4 + index, + name: section, + })), + { + '@type': 'ListItem', + position: 4 + sectionTrail.length, + name: data.title, + item: canonical, + }, + ], + }, + ], } : null; --- diff --git a/src/src/components/starlight/PageTitle.astro b/src/src/components/starlight/PageTitle.astro index 4a01ce9..bab4ae0 100644 --- a/src/src/components/starlight/PageTitle.astro +++ b/src/src/components/starlight/PageTitle.astro @@ -8,6 +8,7 @@ import { channelBasePath, channelDisplayLabel } from '~/lib/docs/channels'; import { docSectionTrail } from '~/lib/docs/sidebar'; import { isStale, STALE_AFTER_DAYS } from '~/lib/docs/staleness'; import { projectChannelLlmsFullPath, projectChannelLlmsPath } from '~/lib/discovery/urls'; +import { topicHubHrefs } from '~/lib/hubs'; import { LLMS_LINK_ATTRS } from '~/lib/llms'; import { getReleaseIndex } from '~/lib/releases/runtime'; import { displayStatus } from '~/lib/status'; @@ -18,6 +19,9 @@ const { entry } = Astro.locals.starlightRoute; const data = entry?.data; const lastReviewed = typeof data?.lastReviewed === 'string' ? data.lastReviewed : undefined; const tags = Array.isArray(data?.tags) ? data.tags : []; +// Only topics that really have a hub page become links, and an alias links the +// canonical hub (see `lib/hubs`). +const topicHrefs = topicHubHrefs(); const experimental = data?.experimental === true; const status = data?.status ? displayStatus({ status: data.status, experimental }) : undefined; @@ -212,11 +216,25 @@ const starCount = { tags.length > 0 && ( <span class="doc-meta-item doc-meta-tags"> - {tags.map((tag) => ( - <span class="doc-tag" title={`Repository topic: ${tag}`}> - {tag} - </span> - ))} + {/* A topic with a hub page becomes a link: the documentation is where a + reader lands from search, so it is also where the browse surface + has to be reachable from. */} + {tags.map((tag) => { + const href = topicHrefs.get(tag); + return href ? ( + <a + href={href} + class="doc-tag" + title={`All projects and guides tagged ${tag}`} + > + {tag} + </a> + ) : ( + <span class="doc-tag" title={`Repository topic: ${tag}`}> + {tag} + </span> + ); + })} </span> ) } diff --git a/src/src/lib/discovery/resources.ts b/src/src/lib/discovery/resources.ts index a455a22..1eb45be 100644 --- a/src/src/lib/discovery/resources.ts +++ b/src/src/lib/discovery/resources.ts @@ -5,11 +5,12 @@ import type { ReleaseCacheData } from '../releases/types'; import type { DiscoverableKind, DiscoverableResource } from './types'; import { existsSync, readdirSync, readFileSync } from 'node:fs'; -import { join, resolve } from 'node:path'; +import { join, relative, resolve } from 'node:path'; import { DOCS_OUTPUT_DIR, readDocsManifest } from '../docs/aggregate'; import { loadProjects } from '../manifest/load'; import { getReleaseIndex } from '../releases/runtime'; +import { findWorkspaceRoot } from '../site-version'; import { firstTimestamp, latestTimestamp, @@ -35,16 +36,88 @@ import { /** * Repo-relative source file for each hand-authored page, so its `lastmod` can be * the commit that last touched it. Keys are normalised route paths (no leading - * or trailing slash). + * or trailing slash); dynamic routes are keyed by a `null` segment. + * + * The index is built by walking `src/pages` rather than being a hand-kept map: a + * page that is not in the map silently falls back to the release cache's + * retrieval time, which is the build time, which is exactly the signal a sitemap + * must never send. Deriving it means a new page (or a new page family) is dated + * correctly the moment it exists. */ -export const PAGE_SOURCES: Readonly<Record<string, string>> = { - '': 'src/src/pages/index.astro', - about: 'src/src/pages/about.astro', - docs: 'src/src/pages/docs/index.astro', - projects: 'src/src/pages/projects/index.astro', - releases: 'src/src/pages/releases/index.astro', - 'use-cases': 'src/src/pages/use-cases/index.astro', -}; +const PAGES_DIR = 'src/src/pages'; + +interface PageSourceIndex { + exact: Map<string, string>; + patterns: { segments: readonly (string | null)[]; file: string }[]; +} + +function buildPageSourceIndex(pagesDir = PAGES_DIR): PageSourceIndex { + const index: PageSourceIndex = { exact: new Map(), patterns: [] }; + // Git paths are workspace-relative, and the scripts run from the `src/` + // package, so the walk has to start at the workspace root to produce keys that + // match `git log --name-only`. + let root: string; + try { + root = findWorkspaceRoot(); + } catch { + return index; + } + const walk = (directory: string, prefix: readonly string[]): void => { + let entries; + try { + entries = readdirSync(directory, { withFileTypes: true }); + } catch { + return; + } + for (const entry of entries) { + if (entry.isDirectory()) { + walk(join(directory, entry.name), [...prefix, entry.name]); + continue; + } + const extension = /\.(astro|md|mdx)$/.exec(entry.name); + if (!extension) { + continue; + } + const base = entry.name.slice(0, -extension[0].length); + const segments = base === 'index' ? [...prefix] : [...prefix, base]; + const file = relative(root, join(directory, entry.name)).replace(/\\/g, '/'); + // `[topic]` addresses any value, so the route it produces cannot be a key. + const patterned = segments.map((segment) => (/^\[.+\]$/.test(segment) ? null : segment)); + if (patterned.some((segment) => segment === null)) { + index.patterns.push({ segments: patterned, file }); + } else { + index.exact.set(segments.join('/'), file); + } + } + }; + walk(resolve(root, pagesDir), []); + return index; +} + +let pageSourceIndexCache: PageSourceIndex | undefined; + +/** The source file that renders a normalised route, or undefined. */ +export function pageSourceFor(route: string): string | undefined { + const index = (pageSourceIndexCache ??= buildPageSourceIndex()); + const direct = index.exact.get(route); + if (direct !== undefined) { + return direct; + } + const segments = route === '' ? [] : route.split('/'); + for (const pattern of index.patterns) { + if (pattern.segments.length !== segments.length) { + continue; + } + if ( + pattern.segments.every( + (segment, position) => segment === null || segment === segments[position], + ) + ) { + return pattern.file; + } + } + return undefined; +} /** * Repo-relative catalogue file for a project id, or `null` when the project owns @@ -282,7 +355,7 @@ export function buildResources( ); } else { lastModified = firstTimestamp([ - ctx.fileDates.get(PAGE_SOURCES[normalized] ?? ''), + ctx.fileDates.get(pageSourceFor(normalized) ?? ''), ctx.fallbackDate, ]); } diff --git a/src/src/lib/docs/aggregate.ts b/src/src/lib/docs/aggregate.ts index 8d1ef25..c3ecbfc 100644 --- a/src/src/lib/docs/aggregate.ts +++ b/src/src/lib/docs/aggregate.ts @@ -10,10 +10,15 @@ import { dirname, join, resolve } from 'node:path'; import { resolveGitHubToken } from '../github/token'; import { getReleaseIndex } from '../releases/runtime'; -import { metaDescription } from '../seo'; +import { docsDescription } from '../seo'; import { OWNER } from '../site'; import { convertGithubAlerts } from './alerts'; -import { channelLayout, releaseDateForRef, resolveDocChannels } from './channels'; +import { + channelDisplayLabel, + channelLayout, + releaseDateForRef, + resolveDocChannels, +} from './channels'; import { applyDiagramBlocks, diagramModelPaths } from './diagrams'; import { extractDescription, @@ -538,12 +543,23 @@ async function buildPage( const repo = getReleaseIndex().data.repos[project.repository]; const repoTags = repo?.topics ?? []; const repoDescription = repo?.description?.trim() || null; - const description = metaDescription( - (slug === 'index' ? project.shortDescription : extractDescription(cleaned)) || - repoDescription || - project.shortDescription, - `${project.name} documentation — open-source .NET tooling from Purview Dev.`, - ); + // A non-default channel is the same product at another version: its pages get + // the same words in a different order, never the same title (ADR 0009). + const channelQualifier = channel.default ? undefined : channelDisplayLabel(channel); + // Extract more than a description's worth of the first paragraph: the + // description is then cut at a sentence boundary inside the 160-character + // range rather than at a word, so a snippet reads as prose instead of as + // scraped text with a trailing ellipsis. + const summary = + (slug === 'index' ? project.shortDescription : extractDescription(cleaned, 400)) || + repoDescription || + project.shortDescription; + const description = docsDescription({ + summary, + pageTitle: title, + projectName: project.name, + qualifier: channelQualifier, + }); const editSourcePath = raw.path.replace(/^\/+/, ''); // A branch can be edited in place; a tag is immutable, so the same link is a // "view source" link. `docsRefKind` tells the EditLink override which it is. diff --git a/src/src/lib/hubs.ts b/src/src/lib/hubs.ts new file mode 100644 index 0000000..2f10e77 --- /dev/null +++ b/src/src/lib/hubs.ts @@ -0,0 +1,289 @@ +import type { DocsManifest } from './docs/aggregate'; +import type { ResolvedProject } from './manifest/load'; +import type { ReleaseCacheData } from './releases/types'; +import type { DisplayStatus } from './status'; + +import { readDocsManifest } from './docs/aggregate'; +import { loadProjects } from './manifest/load'; +import { projectRepoEnrichment } from './releases/repo'; +import { getReleaseIndex } from './releases/runtime'; +import { hubDescription, hubTitle, humaniseTag } from './seo'; +import { displayStatus } from './status'; +import { withBase } from './urls'; + +/** + * Topic and category hubs — the catalogue's metadata turned into crawlable pages. + * + * The site already knows every project's GitHub topics and category, and the + * documentation manifest knows every page. What it did not have was a + * *destination* for the words a reader searches with: "c# source generator", + * "aspire", "event sourcing". A hub is that destination, generated from data + * rather than authored, so it cannot drift from the catalogue. + * + * Two rules keep hubs from becoming thin doorway pages: + * + * - a hub is only published when it indexes at least `MIN_HUB_PROJECTS` + * projects, so the site never ships a page with one link on it; + * - every hub lists the real projects (with their status, description and + * documentation links) and the documentation pages behind them, so the page + * has content of its own rather than being a list of outbound links. + */ + +/** A hub indexing fewer projects than this is not published. */ +export const MIN_HUB_PROJECTS = 2; + +/** Upper bound on the documentation links a single hub lists. */ +export const MAX_HUB_DOC_LINKS = 80; + +/** One project as a hub lists it. */ +export interface HubProject { + id: string; + name: string; + /** Site-relative URL of the catalogue page. */ + url: string; + description: string; + status: DisplayStatus; + category: string; + tags: string[]; + /** Site-relative documentation entry point, or null when the project has none. */ + docsUrl: string | null; + docsPageCount: number; +} + +/** One documentation page as a hub links it. */ +export interface HubDocLink { + title: string; + url: string; + projectName: string; +} + +export interface Hub { + /** Slug used in the URL and as the page parameter. */ + slug: string; + /** Display label (`C#`, `union types`, `Source generation`). */ + label: string; + /** Site-relative path (`/topics/c-sharp/`). */ + path: string; + /** `<title>` subject, without the site name. */ + title: string; + description: string; + projects: HubProject[]; + pages: HubDocLink[]; +} + +export interface HubIndex { + topics: Hub[]; + categories: Hub[]; +} + +/** + * Topic spellings that mean the same thing, canonical spelling last. + * + * GitHub topics are lowercase and hyphenated, but they are also free-form, so the + * same concept arrives spelled two ways ("c-sharp" on one repository, "csharp" on + * another). Grouping them is what keeps a hub from splitting into two half-empty + * pages — and from publishing two pages with the same title. + */ +const TOPIC_ALIASES: Record<string, string> = { + 'asp-net-core': 'aspnetcore', + 'c-sharp': 'csharp', + 'dot-net': 'dotnet', + 'ef-core': 'efcore', + 'entity-framework': 'entityframework', +}; + +/** The canonical spelling of a topic, so aliases share one hub. */ +export function canonicalTopic(tag: string): string { + const normalized = tag.trim().toLowerCase(); + return TOPIC_ALIASES[normalized] ?? normalized; +} + +/** Topics that are legal URL segments (GitHub topics already are). */ +const TOPIC_SLUG = /^[a-z0-9][a-z0-9-]*$/; + +export function topicHubPath(tag: string): string { + return `/topics/${tag}/`; +} + +export function categoryHubPath(category: string): string { + return `/categories/${category}/`; +} + +/** + * The URL an aggregated page is published at. + * + * A page's slug is its path from the docs root (ADR 0011), and an `index` at any + * depth addresses the directory that holds it — Starlight strips that segment, so + * `schemas/index` lives at `/docs/<id>/schemas/`, not at `…/schemas/index/`. + */ +export function docsPageUrl(projectId: string, slug: string): string { + const segments = slug.split('/'); + if (segments[segments.length - 1] === 'index') { + segments.pop(); + } + const path = segments.join('/'); + return path === '' ? `/docs/${projectId}/` : `/docs/${projectId}/${path}/`; +} + +/** Documentation pages of a project's default channel, in manifest order. */ +function defaultChannelPages( + projectId: string, + docsManifest: DocsManifest | null, +): { url: string; title: string; slug: string }[] { + const channel = docsManifest?.projects + .find((entry) => entry.projectId === projectId) + ?.channels.find((candidate) => candidate.default); + if (!channel) { + return []; + } + return channel.pages.map((page) => ({ + slug: page.slug, + title: page.title, + url: docsPageUrl(projectId, page.slug), + })); +} + +/** + * Build every hub from the catalogue, the release cache (which supplies the + * GitHub topics) and the documentation manifest. Deterministic: the same inputs + * produce the same pages in the same order. + */ +export function buildHubs( + projects: readonly ResolvedProject[], + releaseData: ReleaseCacheData, + docsManifest: DocsManifest | null, +): HubIndex { + const active = projects + .filter((project) => project.status !== 'archived') + .toSorted((a, b) => a.order - b.order || a.name.localeCompare(b.name)); + + const byTag = new Map<string, HubProject[]>(); + const byCategory = new Map<string, HubProject[]>(); + const pagesByProject = new Map<string, HubDocLink[]>(); + + for (const project of active) { + const { tags, shortDescription } = projectRepoEnrichment(project, releaseData); + const validTags = tags.filter((tag) => TOPIC_SLUG.test(tag)).toSorted(); + const docs = defaultChannelPages(project.id, docsManifest); + const docsIndex = docs.find((page) => page.slug === 'index'); + const entry: HubProject = { + id: project.id, + name: project.name, + url: `/projects/${project.id}/`, + description: shortDescription, + status: displayStatus(project), + category: project.category, + tags: validTags, + docsUrl: docsIndex?.url ?? (project.docs ? `/docs/${project.id}/` : null), + docsPageCount: docs.length, + }; + pagesByProject.set( + project.id, + docs + .filter((page) => page.slug !== 'index') + .map((page) => ({ title: page.title, url: page.url, projectName: project.name })), + ); + // Aliases of one topic share one hub, and a project that carries two spellings + // of it is listed once (see `canonicalTopic`). + for (const canonical of new Set(validTags.map(canonicalTopic))) { + byTag.set(canonical, [...(byTag.get(canonical) ?? []), entry]); + } + byCategory.set(project.category, [...(byCategory.get(project.category) ?? []), entry]); + } + + const docLinksFor = (entries: readonly HubProject[]): HubDocLink[] => { + const links: HubDocLink[] = []; + for (const entry of entries) { + for (const link of pagesByProject.get(entry.id) ?? []) { + if (links.length >= MAX_HUB_DOC_LINKS) { + return links; + } + links.push(link); + } + } + return links; + }; + + const build = ( + kind: 'topic' | 'category', + slug: string, + label: string, + entries: HubProject[], + ): Hub => ({ + slug, + label, + path: kind === 'topic' ? topicHubPath(slug) : categoryHubPath(slug), + title: hubTitle(label, kind), + description: hubDescription({ label, kind, projectNames: entries.map((entry) => entry.name) }), + projects: entries, + pages: docLinksFor(entries), + }); + + const topics = [...byTag.entries()] + .filter(([, entries]) => entries.length >= MIN_HUB_PROJECTS) + .map(([tag, entries]) => build('topic', tag, humaniseTag(tag), entries)) + .toSorted( + (a, b) => + b.projects.length - a.projects.length || + a.label.localeCompare(b.label) || + a.slug.localeCompare(b.slug), + ); + + // Two distinct topics can still read the same way (`csharp` and `c_sharp` both + // become "C#"), and two pages with one title are two pages competing for one + // query. The slug is the disambiguator of last resort. + const usedTitles = new Set<string>(); + for (const hub of topics) { + if (usedTitles.has(hub.title)) { + hub.title = `${hub.title} (${hub.slug})`; + } + usedTitles.add(hub.title); + } + + const categories = [...byCategory.entries()] + .filter(([, entries]) => entries.length >= MIN_HUB_PROJECTS) + .map(([category, entries]) => build('category', category, category.replace(/-/g, ' '), entries)) + .toSorted((a, b) => a.slug.localeCompare(b.slug)); + + return { topics, categories }; +} + +/** + * Every topic spelling that has a hub, mapped to that hub's href. + * + * A caller asks this instead of comparing tags to slugs, so a chip links only + * where a page exists — and a repository that spells a topic `c-sharp` links the + * canonical `csharp` hub rather than a page that was never built. + */ +export function topicHubHrefs(hubs: HubIndex = getHubs()): Map<string, string> { + const hrefs = new Map<string, string>(); + for (const hub of hubs.topics) { + const href = withBase(hub.path); + hrefs.set(hub.slug, href); + for (const [alias, canonical] of Object.entries(TOPIC_ALIASES)) { + if (canonical === hub.slug) { + hrefs.set(alias, href); + } + } + } + return hrefs; +} + +/** Site-relative href for a hub, base-aware. */ +export function hubHref(hub: Hub): string { + return withBase(hub.path); +} + +let cachedHubs: HubIndex | undefined; + +/** + * The hubs for the site as it is now, derived once per build process. + * + * Pages and components all ask the same question — "does this tag have a hub?" — + * and the answer must be identical everywhere, so it is computed once from the + * catalogue, the release cache and the docs manifest. + */ +export function getHubs(): HubIndex { + cachedHubs ??= buildHubs(loadProjects(), getReleaseIndex().data, readDocsManifest()); + return cachedHubs; +} diff --git a/src/src/lib/manifest/load.ts b/src/src/lib/manifest/load.ts index f0c26d2..ebfac7c 100644 --- a/src/src/lib/manifest/load.ts +++ b/src/src/lib/manifest/load.ts @@ -392,6 +392,22 @@ export function loadProjects(): ResolvedProject[] { return parseManifest(raw, DEFAULT_PROJECTS_DIR, undefined, raw.sources); } +let projectsCache: ResolvedProject[] | undefined; + +/** + * The catalogue, parsed once per process. + * + * Rendering asks for the catalogue many times in one build — every project page, + * and every documentation page that needs its project's display name or category. + * The catalogue cannot change while a build runs, so it is parsed once. A script + * that *writes* manifests and then reads them back runs in its own process + * (`just check-projects`, `just fix-projects`), so it is unaffected. + */ +export function getProjects(): ResolvedProject[] { + projectsCache ??= loadProjects(); + return projectsCache; +} + function withExternalDefaults(record: ExternalProjectRecord): ResolvedExternalProject { return { ...record, diff --git a/src/src/lib/seo.ts b/src/src/lib/seo.ts index e8058af..a95184c 100644 --- a/src/src/lib/seo.ts +++ b/src/src/lib/seo.ts @@ -1,20 +1,394 @@ const MIN_LENGTH = 120; const MAX_LENGTH = 160; -/** Fit a meta description into the 120-160 character range search engines expect. */ +/** + * How long a derived title may get, including the brand suffix. Search engines + * show roughly this much, so a title that runs past it hides its own tail (which + * is where the project name sits). + */ +const TITLE_MAX = 70; + +/** The site name appended to a derived title, with its separator. */ +function brandSuffix(brand: string): string { + return ` | ${brand}`; +} + +/** + * Search-engine metadata for the pages the site generates. + * + * Two rules govern everything here: + * + * 1. **A title leads with the words a reader would search for.** The catalogue + * already carries those words — the package id, `shortDescription`, the + * GitHub topics and the category — so titles are *derived* from metadata + * rather than hand-written per page, and cannot drift from the catalogue. + * 2. **A documentation page names its project.** `Unions | Purview Dev` tells a + * crawler nothing; `Union design — Unions documentation | Purview Dev` says + * which product the page documents, which is what makes a long-tail query + * resolvable. + * + * The module is dependency-free (no imports) so the docs aggregation, the Astro + * config and any page can use it without creating an import cycle. + */ + +/** + * Fit a meta description to what search engines display. + * + * A passage that already fills a description is used as it stands, cut at a + * sentence boundary where there is one (`truncate`). A shorter one is padded with + * `context` — which is why the callers pass a context long enough to matter — and + * only the padded result is cut at a word. + */ export function metaDescription( text: string, context = 'Open-source .NET tooling from Purview Dev.', ): string { - let result = text.replace(/\s+/g, ' ').trim(); - if (result.length < MIN_LENGTH) { - const base = /[.!?…]$/.test(result) ? result : `${result}.`; - result = `${base} ${context}`; + const collapsed = text.replace(/\s+/g, ' ').trim(); + const primary = collapsed.length > MAX_LENGTH ? truncate(collapsed, MAX_LENGTH) : collapsed; + if (primary.length >= MIN_LENGTH || primary.endsWith('…')) { + return primary; + } + const base = /[.!?]$/.test(primary) ? primary : `${primary}.`; + const padded = `${base} ${context}`; + return padded.length > MAX_LENGTH ? truncateWords(padded, MAX_LENGTH) : padded; +} + +/** + * The shortest a sentence-boundary cut may be. Below this a single short sentence + * would throw away more information than it gains in readability, and a word cut + * of the fuller text is the better trade. + */ +const SENTENCE_FLOOR = 70; + +/** Cut to the last whole word inside the limit, marking the cut. */ +export function truncateWords(text: string, limit: number): string { + const cut = text.slice(0, limit); + const lastSpace = cut.lastIndexOf(' '); + return `${(lastSpace > 0 ? cut.slice(0, lastSpace) : cut).replace(/[\s,;:.—-]+$/, '')}…`; +} + +/** + * Truncate a passage to a limit. + * + * A sentence boundary inside the limit wins when at least `SENTENCE_FLOOR` + * characters precede it: a description that ends where the author ended a + * sentence reads as prose in a result snippet, while a mid-paragraph cut reads as + * scraped text. Otherwise the cut falls back to the last whole word. + */ +export function truncate(text: string, limit: number): string { + const cut = text.slice(0, limit); + const sentenceEnd = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? ')); + return sentenceEnd >= SENTENCE_FLOOR ? cut.slice(0, sentenceEnd + 1) : truncateWords(cut, limit); +} + +/** The first sentence of a block of prose, without its terminating punctuation. */ +export function firstSentence(text: string): string { + const collapsed = text.replace(/\s+/g, ' ').trim(); + if (collapsed === '') { + return ''; + } + const match = /^(.*?[.!?])(?:\s|$)/.exec(collapsed); + return (match?.[1] ?? collapsed).replace(/[.!?]+$/, '').trim(); +} +/** Category slugs are catalogue vocabulary; these are the words a reader types. */ +export const CATEGORY_PHRASES: Record<string, string> = { + 'application-framework': 'application framework', + validation: 'validation', + observability: 'observability', + 'source-generation': 'source generation', + 'build-tooling': 'build tooling', + 'developer-tooling': 'developer tooling', + aspire: 'Aspire', +}; + +export function categoryPhrase(category: string): string { + return CATEGORY_PHRASES[category] ?? category.replace(/-/g, ' '); +} + +/** + * Acronyms and spellings that a generic "split on hyphens and capitalise" rule + * gets wrong. This is the topic vocabulary (GitHub topics), not the folder + * vocabulary the docs sidebar uses, so it is deliberately its own map. + */ +const TAG_WORDS: Record<string, string> = { + api: 'API', + aot: 'AOT', + aspnetcore: 'ASP.NET Core', + blazor: 'Blazor', + cli: 'CLI', + cosmosdb: 'Cosmos DB', + 'c-sharp': 'C#', + csharp: 'C#', + cs: 'C#', + dotnet: '.NET', + efcore: 'EF Core', + 'ef-core': 'EF Core', + entityframework: 'Entity Framework', + grpc: 'gRPC', + http: 'HTTP', + https: 'HTTPS', + json: 'JSON', + mcp: 'MCP', + msbuild: 'MSBuild', + mqtt: 'MQTT', + net: '.NET', + net10: '.NET 10', + net11: '.NET 11', + nuget: 'NuGet', + opentelemetry: 'OpenTelemetry', + rabbitmq: 'RabbitMQ', + redis: 'Redis', + roslyn: 'Roslyn', + sdk: 'SDK', + serilog: 'Serilog', + sql: 'SQL', + sqlserver: 'SQL Server', + tunit: 'TUnit', + ui: 'UI', + uri: 'URI', + url: 'URL', + xunit: 'xUnit', + xml: 'XML', + yaml: 'YAML', + zod: 'Zod', + zodsharp: 'ZodSharp', +}; + +/** Display form of one topic: `c-sharp` -> `C#`, `value-types` -> `value types`. */ +export function humaniseTag(tag: string): string { + // A single word may spell out several (`c-sharp`, `ef-core`, `net11`), so the + // whole tag is looked up before it is split. + const whole = TAG_WORDS[tag.trim().toLowerCase()]; + if (whole !== undefined) { + return whole; + } + return tag + .split(/[-_]+/) + .filter((word) => word !== '') + .map((word) => TAG_WORDS[word.toLowerCase()] ?? word) + .join(' '); +} + +/** The fields of a catalogue project that derived metadata is built from. */ +export interface SeoProjectFacts { + name: string; + shortDescription: string; + category: string; + packages?: readonly { id: string; primary?: boolean }[]; + /** GitHub topics, read through the release cache. */ + tags?: readonly string[]; + targetFrameworks?: readonly string[]; +} + +/** + * The name a reader searches for: the primary package id when the project + * publishes one (`Purview.Unions`), otherwise the catalogue display name. + */ +export function productName(project: SeoProjectFacts): string { + const primary = project.packages?.find((pkg) => pkg.primary) ?? project.packages?.[0]; + return primary?.id ?? project.name; +} + +/** + * `<title>` for a project's catalogue page. + * + * `Purview.Unions — Dependency-free C# 15 unions that do not box value-type cases` + * + * The product name leads, so the keyword phrase is what gets trimmed when the pair + * would run past what a result shows. The phrase is preferred over the category + * because it is the words a reader searches with; the category is the fallback. + */ +export function projectPageTitle( + project: SeoProjectFacts, + options: { brand?: string } = {}, +): string { + const { brand = 'Purview Dev' } = options; + const product = productName(project); + const phrase = firstSentence(project.shortDescription); + // What is left for the phrase once the product name, its separator and the brand + // have taken their share of the title. + const budget = TITLE_MAX - brandSuffix(brand).length - product.length - 3; + const trimmed = trimPhrase(phrase, Math.max(24, budget)); + return fitTitle( + [ + `${product} — ${phrase}`, + // A trimmed phrase shorter than this says less than the category does. + ...(trimmed.length >= 20 ? [`${product} — ${trimmed}`] : []), + `${product} — ${categoryPhrase(project.category)}`, + product, + ], + brand, + ); +} + +/** Meta description for a project's catalogue page. */ +export function projectPageDescription(project: SeoProjectFacts): string { + const frameworks = project.targetFrameworks?.length + ? ` Targets ${project.targetFrameworks.join(', ')}.` + : ''; + const topics = project.tags?.slice(0, 6).join(', ') ?? ''; + return metaDescription( + `${firstSentence(project.shortDescription)}.${frameworks}${topics ? ` Topics: ${topics}.` : ''}`, + `${project.name} — ${categoryPhrase(project.category)} from Purview Dev, with installation, use cases and documentation.`, + ); +} + +/** + * Pick the first shape that fits the title budget. + * + * The shapes are ordered from most to least informative, and every one of them + * identifies the page: the last candidate is used even when it overruns, because a + * duplicate title (two pages competing for one slot) is a worse failure than a + * long one, and search engines cut the tail rather than the head. + */ +function fitTitle(candidates: readonly string[], brand: string): string { + const suffix = brandSuffix(brand); + const fits = candidates.find((candidate) => candidate.length + suffix.length <= TITLE_MAX); + return `${fits ?? candidates[candidates.length - 1]}${suffix}`; +} + +/** Words a title phrase may not end on: a trimmed phrase must end on content. */ +const DANGLING_WORDS = new Set([ + 'a', + 'an', + 'and', + 'as', + 'at', + 'but', + 'by', + 'do', + 'does', + 'for', + 'from', + 'in', + 'into', + 'is', + 'it', + 'of', + 'on', + 'or', + 'that', + 'the', + 'to', + 'which', + 'with', + 'without', +]); + +/** A keyword phrase shortened to a word boundary, without ending on a stop word. */ +function trimPhrase(phrase: string, limit: number): string { + if (phrase.length <= limit) { + return phrase; } - if (result.length > MAX_LENGTH) { - const cut = result.slice(0, MAX_LENGTH - 1); - const lastSpace = cut.lastIndexOf(' '); - result = `${(lastSpace > 0 ? cut.slice(0, lastSpace) : cut).replace(/[\s,;:.—-]+$/, '')}…`; + const cut = phrase.slice(0, limit); + const lastSpace = cut.lastIndexOf(' '); + const words = (lastSpace > 0 ? cut.slice(0, lastSpace) : cut).split(' ').filter(Boolean); + while (words.length > 0 && DANGLING_WORDS.has((words[words.length - 1] ?? '').toLowerCase())) { + words.pop(); } - return result; + return words.join(' ').replace(/[\s,;:.—-]+$/, ''); +} + +/** + * `<title>` for a project's documentation landing page. + * + * The landing page is a different page from the catalogue page, so it gets a + * different title. Keeping both as the project name alone would make the two + * compete for the same query. + */ +export function docsIndexTitle( + project: SeoProjectFacts, + options: { qualifier?: string; brand?: string } = {}, +): string { + const { qualifier, brand = 'Purview Dev' } = options; + const version = qualifier ? ` (${qualifier})` : ''; + return fitTitle( + [ + `${project.name} documentation — ${categoryPhrase(project.category)} for .NET${version}`, + `${project.name} documentation${version}`, + `${project.name} documentation`, + ], + brand, + ); +} + +/** + * `<title>` for one aggregated documentation page. + * + * The project name is always in the returned title — a documentation page whose + * title omits its product is unreachable from a search for that product — and the + * section and the word "documentation" are dropped, in that order, when keeping + * them would push the title past what a result shows. + */ +export function docsPageTitle(options: { + pageTitle: string; + projectName: string; + /** Display labels of the folders the page sits in, outermost first (ADR 0011). */ + sectionTrail?: readonly string[]; + /** + * Version qualifier for a non-default documentation channel (`Prerelease`), so + * the two versions of the same page never share a search-result title. + */ + qualifier?: string; + /** Site name appended to the title. */ + brand?: string; +}): string { + const { pageTitle, projectName, sectionTrail = [], qualifier, brand = 'Purview Dev' } = options; + const section = sectionTrail.length > 0 ? `${sectionTrail.join(' · ')} · ` : ''; + const version = qualifier ? ` (${qualifier})` : ''; + // What is left for the page's own title once the project name, its separator and + // the brand have taken their share. + const budget = TITLE_MAX - brandSuffix(brand).length - projectName.length - 3 - version.length; + const trimmed = trimPhrase(pageTitle, Math.max(16, budget)); + return fitTitle( + [ + `${section}${pageTitle} — ${projectName} documentation${version}`, + `${section}${pageTitle} — ${projectName}${version}`, + // A trimmed title below this says less than the project name does. + ...(trimmed.length >= 8 ? [`${trimmed} — ${projectName}${version}`] : []), + // Never less than this: the page's own title, whole. + `${pageTitle} — ${projectName}${version}`, + ], + brand, + ); +} + +/** Meta description for one aggregated documentation page. */ +export function docsDescription(options: { + summary: string; + pageTitle: string; + projectName: string; + /** Version qualifier for a non-default documentation channel (`Prerelease`). */ + qualifier?: string; +}): string { + const { summary, pageTitle, projectName, qualifier } = options; + const version = qualifier ? ` (${qualifier})` : ''; + return metaDescription( + summary, + `${pageTitle} in the ${projectName} documentation${version} — open-source .NET tooling from Purview Dev.`, + ); +} + +/** `<title>` subject for a topic or category hub page. */ +export function hubTitle(label: string, kind: 'topic' | 'category'): string { + const subject = label.charAt(0).toUpperCase() + label.slice(1); + return kind === 'topic' + ? `${subject} — Purview .NET projects and guides` + : `${subject} — Purview .NET projects`; +} + +/** Meta description for a topic or category hub page, naming what it indexes. */ +export function hubDescription(options: { + label: string; + kind: 'topic' | 'category'; + projectNames: readonly string[]; +}): string { + const { label, kind, projectNames } = options; + const names = projectNames.join(', '); + return metaDescription( + kind === 'topic' + ? `Open-source .NET projects and documentation tagged ${label}: ${names}.` + : `Purview .NET ${label} projects: ${names}.`, + `Browse the ${label} projects, their packages, use cases and documentation.`, + ); } diff --git a/src/src/pages/categories/[category].astro b/src/src/pages/categories/[category].astro new file mode 100644 index 0000000..80965ec --- /dev/null +++ b/src/src/pages/categories/[category].astro @@ -0,0 +1,86 @@ +--- +import HubBody from '~/components/HubBody.astro'; +import SiteLayout from '~/layouts/SiteLayout.astro'; +import { getHubs } from '~/lib/hubs'; +import { SITE } from '~/lib/site'; +import { absoluteUrl, withBase } from '~/lib/urls'; + +export function getStaticPaths() { + return getHubs().categories.map((hub) => ({ params: { category: hub.slug }, props: { hub } })); +} + +interface Props { + hub: ReturnType<typeof getHubs>['categories'][number]; +} + +const { hub } = Astro.props; +const structuredData = { + '@context': 'https://schema.org', + '@graph': [ + { + '@type': 'CollectionPage', + name: hub.title, + description: hub.description, + url: absoluteUrl(hub.path), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + }, + { + '@type': 'ItemList', + name: `${hub.label} projects`, + numberOfItems: hub.projects.length, + itemListElement: hub.projects.map((project, index) => ({ + '@type': 'ListItem', + position: index + 1, + name: project.name, + url: absoluteUrl(project.url), + })), + }, + { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', item: absoluteUrl('/') }, + { '@type': 'ListItem', position: 2, name: 'Categories', item: absoluteUrl('/categories/') }, + { '@type': 'ListItem', position: 3, name: hub.label, item: absoluteUrl(hub.path) }, + ], + }, + ], +}; +--- + +<SiteLayout + title={`${hub.title} | ${SITE.fullName}`} + description={hub.description} + structuredData={structuredData} +> + <div class="pv-container py-12 md:py-16"> + <nav aria-label="Breadcrumb" class="mb-6 text-sm text-muted"> + <a href={withBase('/')} class="pv-link">Home</a> + <span aria-hidden="true"> / </span> + <a href={withBase('/categories/')} class="pv-link">Categories</a> + <span aria-hidden="true"> / </span> + <span class="text-foreground">{hub.label}</span> + </nav> + + <div class="max-w-3xl"> + <p class="pv-chip mb-4 border-brand/30 bg-brand/5 text-brand">Category</p> + <h1 class="text-3xl font-bold tracking-tight md:text-4xl">{hub.label}</h1> + <p class="mt-4 text-lg text-muted"> + {hub.projects.length} Purview projects in the {hub.label} category, with the documentation + they publish. Each one is a .NET library or tool you can adopt on its own. + </p> + </div> + + <HubBody hub={hub} kind="category" /> + + <section class="mt-12 rounded-xl border border-border bg-surface p-6 md:p-8"> + <h2 class="text-xl font-semibold">Browse differently</h2> + <p class="mt-3 max-w-2xl text-sm text-muted"> + See the whole <a href={withBase('/projects/')} class="pv-link">project catalogue</a>, browse{' '} + <a href={withBase('/topics/')} class="pv-link">topics</a> such as C#, Roslyn or Aspire, or + every <a href={withBase('/packages/')} class="pv-link">package</a> the family publishes. + </p> + </section> + </div> +</SiteLayout> diff --git a/src/src/pages/categories/index.astro b/src/src/pages/categories/index.astro new file mode 100644 index 0000000..67d11ff --- /dev/null +++ b/src/src/pages/categories/index.astro @@ -0,0 +1,79 @@ +--- +import SiteLayout from '~/layouts/SiteLayout.astro'; +import { getHubs, hubHref } from '~/lib/hubs'; +import { SITE } from '~/lib/site'; +import { absoluteUrl, withBase } from '~/lib/urls'; + +const { categories, topics } = getHubs(); +const structuredData = { + '@context': 'https://schema.org', + '@type': 'CollectionPage', + name: 'Categories', + description: 'The categories the Purview .NET projects belong to.', + url: absoluteUrl('/categories/'), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, +}; +--- + +<SiteLayout + title={`Categories — Purview .NET projects | ${SITE.fullName}`} + description="Purview's open-source .NET projects grouped by category — source generation, validation, observability, Aspire, build tooling and application frameworks." + structuredData={structuredData} +> + <div class="pv-container py-12 md:py-16"> + <nav aria-label="Breadcrumb" class="mb-6 text-sm text-muted"> + <a href={withBase('/')} class="pv-link">Home</a> + <span aria-hidden="true"> / </span> + <span class="text-foreground">Categories</span> + </nav> + + <div class="max-w-3xl"> + <p class="pv-chip mb-4 border-brand/30 bg-brand/5 text-brand">Categories</p> + <h1 class="text-3xl font-bold tracking-tight md:text-4xl">Categories</h1> + <p class="mt-4 text-lg text-muted"> + What the projects are for, rather than what they are tagged with. Open a category for the + projects in it and the documentation they publish. + </p> + </div> + + <div class="mt-10 grid gap-5 sm:grid-cols-2 lg:grid-cols-3"> + { + categories.map((hub) => ( + <div class="pv-card flex flex-col gap-3 p-5"> + <h2 class="text-lg font-semibold leading-snug"> + <a href={hubHref(hub)} class="pv-link"> + {hub.label} + </a> + </h2> + <ul class="mt-1 list-none space-y-1 text-sm"> + {hub.projects.map((project) => ( + <li> + <a href={withBase(project.url)} class="pv-link"> + {project.name} + </a> + </li> + ))} + </ul> + </div> + )) + } + </div> + + <section class="mt-12 rounded-xl border border-border bg-surface p-6 md:p-8"> + <h2 class="text-xl font-semibold">Browse by topic instead</h2> + <p class="mt-3 max-w-2xl text-sm text-muted"> + <a href={withBase('/topics/')} class="pv-link">Topics</a> slice the same projects by the + technology they use{ + topics.length > 0 + ? ` — ${topics + .slice(0, 5) + .map((hub) => hub.label.toLowerCase()) + .join(', ')} and more.` + : '.' + } + </p> + </section> + </div> +</SiteLayout> diff --git a/src/src/pages/docs/index.astro b/src/src/pages/docs/index.astro index c165f9e..8799278 100644 --- a/src/src/pages/docs/index.astro +++ b/src/src/pages/docs/index.astro @@ -9,7 +9,7 @@ import { projectChannelLlmsFullPath, projectChannelLlmsPath } from '~/lib/discov import { projectRepoEnrichment } from '~/lib/releases/repo'; import { getReleaseIndex } from '~/lib/releases/runtime'; import { SITE } from '~/lib/site'; -import { withBase } from '~/lib/urls'; +import { absoluteUrl, withBase } from '~/lib/urls'; const projects = loadProjects().filter( (project) => project.docs && project.status !== 'archived', @@ -28,11 +28,38 @@ const pageCount = docsManifest?.projects.reduce( (total, entry) => total + entry.channels.reduce((count, channel) => count + channel.pages.length, 0), 0, ); +// The portal is an index of documentation sets, one per project. +const structuredData = { + '@context': 'https://schema.org', + '@graph': [ + { + '@type': 'CollectionPage', + name: 'Documentation', + description: "Documentation for Purview's .NET projects, aggregated from the repositories.", + url: absoluteUrl('/docs/'), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + }, + { + '@type': 'ItemList', + name: 'Purview documentation', + numberOfItems: projects.length, + itemListElement: projects.map((project, index) => ({ + '@type': 'ListItem', + position: index + 1, + name: `${project.name} documentation`, + url: absoluteUrl(`/docs/${project.id}/`), + })), + }, + ], +}; --- <SiteLayout title={`Documentation — ${SITE.fullName}`} description="Searchable documentation for Purview's .NET projects, brought together from the repositories that own it." + structuredData={structuredData} > <div class="pv-container py-12 md:py-16"> <div class="max-w-3xl"> diff --git a/src/src/pages/examples/astroc4.mdx b/src/src/pages/examples/astroc4.mdx index e1a0982..aaca9cf 100644 --- a/src/src/pages/examples/astroc4.mdx +++ b/src/src/pages/examples/astroc4.mdx @@ -1,12 +1,16 @@ --- -layout: ../../layouts/SiteLayout.astro title: AstroC4 in action — Purview Dev description: A live LikeC4 model, an inline fence, a deployment view and LikeC4 syntax highlighting, rendered by AstroC4 on this page. --- import LikeC4View from '@purview-dev/astroc4/components/LikeC4View.astro'; +import SiteLayout from '~/layouts/SiteLayout.astro'; import { withBase } from '~/lib/urls'; +<SiteLayout + title="AstroC4 in action — Purview Dev" + description="A live LikeC4 model, an inline fence, a deployment view and LikeC4 syntax highlighting, rendered by AstroC4 on this page." +> <div class="pv-container py-12 md:py-16"> <div class="max-w-4xl"> <nav aria-label="Breadcrumb" class="text-muted mb-6 text-sm"> @@ -226,3 +230,4 @@ model { </div> </div> +</SiteLayout> diff --git a/src/src/pages/packages/index.astro b/src/src/pages/packages/index.astro new file mode 100644 index 0000000..2b93886 --- /dev/null +++ b/src/src/pages/packages/index.astro @@ -0,0 +1,117 @@ +--- +import SiteLayout from '~/layouts/SiteLayout.astro'; +import { loadProjects } from '~/lib/manifest/load'; +import { getReleaseIndex } from '~/lib/releases/runtime'; +import { projectReleaseSummary } from '~/lib/releases/transform'; +import { SITE } from '~/lib/site'; +import { absoluteUrl, packagePageUrl, registryLabel, withBase } from '~/lib/urls'; + +// Every package the family publishes, with the version a reader can install +// today. Derived from the catalogue and the release cache, so the page cannot +// list a package that no longer ships. +const projects = loadProjects().filter((project) => project.status !== 'archived'); +const releaseIndex = getReleaseIndex(); +const rows = projects.flatMap((project) => { + const summary = projectReleaseSummary(project, releaseIndex.data, releaseIndex.source); + return project.packages.map((pkg) => { + const release = summary.packages.find((candidate) => candidate.packageId === pkg.id); + return { + projectId: project.id, + projectName: project.name, + packageId: pkg.id, + registry: pkg.registry, + primary: pkg.primary ?? false, + version: release?.latestStable ?? release?.latestPrerelease ?? null, + deprecated: release?.deprecated ?? false, + pageUrl: packagePageUrl(pkg.registry, pkg.id), + }; + }); +}); + +const structuredData = { + '@context': 'https://schema.org', + '@type': 'CollectionPage', + name: 'Packages', + description: 'Every NuGet and npm package the Purview .NET projects publish.', + url: absoluteUrl('/packages/'), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, +}; +--- + +<SiteLayout + title={`Packages — Purview .NET libraries and tools | ${SITE.fullName}`} + description={`Every package the Purview family publishes — ${rows.length} NuGet and npm packages across ${projects.length} projects, with the version each one ships today.`} + structuredData={structuredData} +> + <div class="pv-container py-12 md:py-16"> + <nav aria-label="Breadcrumb" class="mb-6 text-sm text-muted"> + <a href={withBase('/')} class="pv-link">Home</a> + <span aria-hidden="true"> / </span> + <span class="text-foreground">Packages</span> + </nav> + + <div class="max-w-3xl"> + <p class="pv-chip mb-4 border-brand/30 bg-brand/5 text-brand">Packages</p> + <h1 class="text-3xl font-bold tracking-tight md:text-4xl">Packages</h1> + <p class="mt-4 text-lg text-muted"> + {rows.length} packages across {projects.length} open-source .NET projects. Install one, or read + the project page for what it does and when it fits. + </p> + </div> + + <div class="mt-10 overflow-x-auto"> + <table class="w-full min-w-[42rem] border-collapse text-sm"> + <caption class="sr-only">Purview packages by project</caption> + <thead> + <tr class="border-b border-border text-left text-muted"> + <th scope="col" class="py-3 pr-4 font-medium">Package</th> + <th scope="col" class="py-3 pr-4 font-medium">Project</th> + <th scope="col" class="py-3 pr-4 font-medium">Registry</th> + <th scope="col" class="py-3 pr-4 font-medium">Version</th> + </tr> + </thead> + <tbody> + { + rows.map((row) => ( + <tr class="border-b border-border align-top"> + <th scope="row" class="py-3 pr-4 text-left font-mono text-xs font-medium"> + <a + href={row.pageUrl} + rel="noopener noreferrer" + target="_blank" + class="pv-link inline-flex items-center gap-1.5" + > + {row.packageId} + </a> + {row.primary && <span class="pv-chip ml-2">primary</span>} + </th> + <td class="py-3 pr-4"> + <a href={withBase(`/projects/${row.projectId}/`)} class="pv-link"> + {row.projectName} + </a> + </td> + <td class="py-3 pr-4">{registryLabel(row.registry)}</td> + <td class="py-3 pr-4 font-mono text-xs"> + {row.version ?? '—'} + {row.deprecated && <span class="pv-chip ml-2">deprecated</span>} + </td> + </tr> + )) + } + </tbody> + </table> + </div> + + <section class="mt-12 rounded-xl border border-border bg-surface p-6 md:p-8"> + <h2 class="text-xl font-semibold">Where to go next</h2> + <p class="mt-3 max-w-2xl text-sm text-muted"> + The <a href={withBase('/projects/')} class="pv-link">project catalogue</a> explains what each + package is for; the <a href={withBase('/docs/')} class="pv-link">documentation</a> has the + guides, and the <a href={withBase('/releases/')} class="pv-link">releases page</a> tracks + versions over time. + </p> + </section> + </div> +</SiteLayout> diff --git a/src/src/pages/projects/[project].astro b/src/src/pages/projects/[project].astro index 0c6b530..6976897 100644 --- a/src/src/pages/projects/[project].astro +++ b/src/src/pages/projects/[project].astro @@ -11,6 +11,8 @@ import StarOnGitHub from '~/components/StarOnGitHub.astro'; import StatusBadge from '~/components/StatusBadge.astro'; import UseCaseCard from '~/components/UseCaseCard.astro'; import { buildBadge, nugetDownloadsBadge, nugetVersionBadge, actionsUrl } from '~/lib/badges';import { readDocsManifest, type DocsManifestChannel } from '~/lib/docs/aggregate'; +import { topicHubHrefs } from '~/lib/hubs'; +import { projectPageDescription, projectPageTitle } from '~/lib/seo'; import { channelBasePath, channelDisplayLabel } from '~/lib/docs/channels'; import { projectChannelLlmsFullPath, projectChannelLlmsPath } from '~/lib/discovery/urls'; import { installAnchorId, installKindFor, installTabs } from '~/lib/install'; @@ -130,6 +132,7 @@ const structuredData: Record<string, unknown> = { // omitted rather than asserted. ...(primaryPackage?.registry === 'nuget' ? { programmingLanguage: 'C#' } : {}), license: 'https://opensource.org/licenses/MIT', + author: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, ...(tags.length > 0 ? { keywords: tags.join(', ') } : {}), ...(primaryPackage ? { @@ -139,6 +142,30 @@ const structuredData: Record<string, unknown> = { : {}), ...(releases.latestRelease?.tagName ? { softwareVersion: releases.latestRelease.tagName } : {}), }, + { + // The package is what a reader actually installs, so it is also described + // as an application: free, cross-platform and versioned by the release the + // page shows. Only accurate values are asserted. + '@type': 'SoftwareApplication', + name: project.name, + applicationCategory: 'DeveloperApplication', + operatingSystem: 'Windows, macOS, Linux', + url: absoluteUrl(`/projects/${project.id}/`), + description: project.shortDescription, + license: 'https://opensource.org/licenses/MIT', + author: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' }, + ...(primaryPackage ? + { + identifier: primaryPackage.id, + downloadUrl: packagePageUrl(primaryPackage.registry, primaryPackage.id), + } + : {}), + ...((project.targetFrameworks ?? []).length > 0 ? + { softwareRequirements: `Targets ${(project.targetFrameworks ?? []).join(', ')}` } + : {}), + ...(releases.latestRelease?.tagName ? { softwareVersion: releases.latestRelease.tagName } : {}), + }, { '@type': 'BreadcrumbList', itemListElement: [ @@ -160,6 +187,27 @@ const structuredData: Record<string, unknown> = { }; const targetFrameworks = project.targetFrameworks ?? []; const installKind = installKindFor(project); +// Search-result metadata is derived from the catalogue, so the title leads with +// the words a reader searches for and cannot drift from the manifest. +const seoFacts = { + name: project.name, + shortDescription: project.shortDescription, + category: project.category, + packages: project.packages, + tags, + targetFrameworks, +}; +// Topic hubs are generated from the same GitHub topics the chips show, so a chip +// links only when its hub really exists (see `lib/hubs`). +const topicHrefs = topicHubHrefs(); +// Each use case names the documentation page it opens, so the link text carries +// the words of its destination instead of one repeated generic label. +const docsPageTitles = new Map( + (docsEntry?.channels.find((channel) => channel.default)?.pages ?? []).map((page) => [ + page.slug, + page.title, + ]), +); const installSections = status !== 'archived' ? project.packages.map((pkg) => { @@ -197,8 +245,8 @@ const packageRows: PackageRow[] = releases.packages.map((pkg) => ({ --- <SiteLayout - title={`${project.name} — ${SITE.fullName}`} - description={project.shortDescription} + title={projectPageTitle(seoFacts, { brand: SITE.fullName })} + description={projectPageDescription(seoFacts)} structuredData={structuredData} alternateLinks={alternateLinks} > @@ -219,11 +267,25 @@ const packageRows: PackageRow[] = releases.packages.map((pkg) => ({ { tags.length > 0 && ( <div class="mt-4 flex flex-wrap gap-2"> - {tags.map((tag) => ( - <span class="pv-chip" title={`Repository topic: ${tag}`}> - {tag} - </span> - ))} + {tags.map((tag) => { + const href = topicHrefs.get(tag); + return href ? ( + <a + href={href} + class="pv-chip no-underline" + title={`All projects and guides tagged ${tag}`} + > + {tag} + </a> + ) : ( + <span class="pv-chip" title={`Repository topic: ${tag}`}> + {tag} + </span> + ); + })} + <a href={withBase('/topics/')} class="pv-chip no-underline text-muted"> + All topics → + </a> </div> ) } @@ -500,6 +562,7 @@ const packageRows: PackageRow[] = releases.packages.map((pkg) => ({ projectName={project.name} projectId={project.id} docsBase={docsPath} + docsLabel={useCase.docsPage ? docsPageTitles.get(useCase.docsPage) : undefined} showProject={false} /> ))} diff --git a/src/src/pages/projects/index.astro b/src/src/pages/projects/index.astro index 3223349..723de13 100644 --- a/src/src/pages/projects/index.astro +++ b/src/src/pages/projects/index.astro @@ -4,11 +4,13 @@ import InlineProse from '~/components/InlineProse.astro'; import ProjectCard from '~/components/ProjectCard.astro'; import ProjectFilter from '~/components/islands/ProjectFilter.tsx'; import StatusBadge from '~/components/StatusBadge.astro'; +import { getHubs, hubHref } from '~/lib/hubs'; import { loadExternalProjects, loadProjects } from '~/lib/manifest/load'; import { projectRepoEnrichment } from '~/lib/releases/repo'; import { getReleaseIndex } from '~/lib/releases/runtime'; import { SITE } from '~/lib/site'; import { displayStatus } from '~/lib/status'; +import { absoluteUrl, withBase } from '~/lib/urls'; const projects = loadProjects(); @@ -16,11 +18,40 @@ const externalProjects = loadExternalProjects(); const releaseIndex = getReleaseIndex(); const categories = [...new Set(projects.map((project) => project.category))].toSorted(); const statuses = ['stable', 'preview', 'experimental']; +// Topics with their own hub page, for the crawlable browse strip. +const topics = getHubs().topics; +// The catalogue is an index of real projects, so it says so. +const structuredData = { + '@context': 'https://schema.org', + '@graph': [ + { + '@type': 'CollectionPage', + name: 'Projects', + description: 'The Purview-Dev catalogue of open-source .NET projects.', + url: absoluteUrl('/projects/'), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + }, + { + '@type': 'ItemList', + name: 'Purview projects', + numberOfItems: projects.length, + itemListElement: projects.map((project, index) => ({ + '@type': 'ListItem', + position: index + 1, + name: project.name, + url: absoluteUrl(`/projects/${project.id}/`), + })), + }, + ], +}; --- <SiteLayout title={`Projects — ${SITE.fullName}`} description="Explore Purview's open-source .NET tools for event sourcing, telemetry, validation, source generation, Aspire, and build automation." + structuredData={structuredData} > <div class="pv-container py-12 md:py-16"> <div class="max-w-3xl"> @@ -36,6 +67,28 @@ const statuses = ['stable', 'preview', 'experimental']; <ProjectFilter client:visible categories={categories} statuses={statuses} /> </div> + { + /* A crawlable way through the catalogue. The filter above is client-side, + so without this the only server-rendered path between projects is the + full list itself. */ + topics.length > 0 && ( + <nav aria-label="Browse projects" class="mt-8 flex flex-wrap items-center gap-2"> + <span class="text-sm text-muted">Browse by topic:</span> + {topics.slice(0, 12).map((hub) => ( + <a href={hubHref(hub)} class="pv-chip no-underline"> + {hub.label} + </a> + ))} + <a href={withBase('/topics/')} class="pv-chip no-underline text-muted"> + All topics → + </a> + <a href={withBase('/categories/')} class="pv-chip no-underline text-muted"> + Categories + </a> + </nav> + ) + } + <div class="mt-8 grid gap-5 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4"> { projects.map((project) => { diff --git a/src/src/pages/topics/[topic].astro b/src/src/pages/topics/[topic].astro new file mode 100644 index 0000000..ffa7df3 --- /dev/null +++ b/src/src/pages/topics/[topic].astro @@ -0,0 +1,89 @@ +--- +import HubBody from '~/components/HubBody.astro'; +import SiteLayout from '~/layouts/SiteLayout.astro'; +import { getHubs } from '~/lib/hubs'; +import { SITE } from '~/lib/site'; +import { absoluteUrl, withBase } from '~/lib/urls'; + +export function getStaticPaths() { + return getHubs().topics.map((hub) => ({ params: { topic: hub.slug }, props: { hub } })); +} + +interface Props { + hub: ReturnType<typeof getHubs>['topics'][number]; +} + +const { hub } = Astro.props; +// A hub is a collection of real projects, so it is described as one: the +// ItemList is what search engines read as "this page is the index of these". +const structuredData = { + '@context': 'https://schema.org', + '@graph': [ + { + '@type': 'CollectionPage', + name: hub.title, + description: hub.description, + url: absoluteUrl(hub.path), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + }, + { + '@type': 'ItemList', + name: `${hub.label} projects`, + numberOfItems: hub.projects.length, + itemListElement: hub.projects.map((project, index) => ({ + '@type': 'ListItem', + position: index + 1, + name: project.name, + url: absoluteUrl(project.url), + })), + }, + { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', item: absoluteUrl('/') }, + { '@type': 'ListItem', position: 2, name: 'Topics', item: absoluteUrl('/topics/') }, + { '@type': 'ListItem', position: 3, name: hub.label, item: absoluteUrl(hub.path) }, + ], + }, + ], +}; +--- + +<SiteLayout + title={`${hub.title} | ${SITE.fullName}`} + description={hub.description} + structuredData={structuredData} +> + <div class="pv-container py-12 md:py-16"> + <nav aria-label="Breadcrumb" class="mb-6 text-sm text-muted"> + <a href={withBase('/')} class="pv-link">Home</a> + <span aria-hidden="true"> / </span> + <a href={withBase('/topics/')} class="pv-link">Topics</a> + <span aria-hidden="true"> / </span> + <span class="text-foreground">{hub.label}</span> + </nav> + + <div class="max-w-3xl"> + <p class="pv-chip mb-4 border-brand/30 bg-brand/5 text-brand">Topic</p> + <h1 class="text-3xl font-bold tracking-tight md:text-4xl">{hub.label}</h1> + <p class="mt-4 text-lg text-muted"> + {hub.projects.length} Purview projects and {hub.pages.length} documentation pages tagged{' '} + <span class="text-foreground">{hub.label}</span>. Purview is a family of open-source .NET + libraries and tools — adopt one piece without replacing what already works. + </p> + </div> + + <HubBody hub={hub} kind="topic" /> + + <section class="mt-12 rounded-xl border border-border bg-surface p-6 md:p-8"> + <h2 class="text-xl font-semibold">Browse differently</h2> + <p class="mt-3 max-w-2xl text-sm text-muted"> + See the whole <a href={withBase('/projects/')} class="pv-link">project catalogue</a>, the{' '} + <a href={withBase('/categories/')} class="pv-link">categories</a> the projects belong to, or + every <a href={withBase('/packages/')} class="pv-link">package</a> the family publishes. + </p> + </section> + </div> +</SiteLayout> diff --git a/src/src/pages/topics/index.astro b/src/src/pages/topics/index.astro new file mode 100644 index 0000000..6999002 --- /dev/null +++ b/src/src/pages/topics/index.astro @@ -0,0 +1,102 @@ +--- +import SiteLayout from '~/layouts/SiteLayout.astro'; +import { getHubs, hubHref } from '~/lib/hubs'; +import { SITE } from '~/lib/site'; +import { absoluteUrl, withBase } from '~/lib/urls'; + +const { topics, categories } = getHubs(); +const structuredData = { + '@context': 'https://schema.org', + '@graph': [ + { + '@type': 'CollectionPage', + name: 'Topics', + description: 'Every topic the Purview .NET projects are tagged with.', + url: absoluteUrl('/topics/'), + inLanguage: 'en', + isPartOf: { '@type': 'WebSite', name: SITE.fullName, url: SITE.url }, + publisher: { '@type': 'Organization', name: SITE.orgName, url: SITE.url }, + }, + { + '@type': 'ItemList', + name: 'Purview topics', + numberOfItems: topics.length, + itemListElement: topics.map((hub, index) => ({ + '@type': 'ListItem', + position: index + 1, + name: hub.label, + url: absoluteUrl(hub.path), + })), + }, + ], +}; +--- + +<SiteLayout + title={`Topics — Purview .NET projects | ${SITE.fullName}`} + description="Browse Purview's open-source .NET projects and documentation by topic — C#, Roslyn source generators, value types, unions, Aspire, telemetry and validation." + structuredData={structuredData} +> + <div class="pv-container py-12 md:py-16"> + <nav aria-label="Breadcrumb" class="mb-6 text-sm text-muted"> + <a href={withBase('/')} class="pv-link">Home</a> + <span aria-hidden="true"> / </span> + <span class="text-foreground">Topics</span> + </nav> + + <div class="max-w-3xl"> + <p class="pv-chip mb-4 border-brand/30 bg-brand/5 text-brand">Topics</p> + <h1 class="text-3xl font-bold tracking-tight md:text-4xl">Topics</h1> + <p class="mt-4 text-lg text-muted"> + Every topic the Purview projects are tagged with on GitHub. Each one opens the projects that + carry it and the documentation pages behind them. + </p> + </div> + + <ul class="mt-10 grid list-none gap-3 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4"> + { + topics.map((hub) => ( + <li> + <a + href={hubHref(hub)} + class="pv-card pv-card-interactive flex items-center justify-between gap-3 p-4 no-underline" + > + <span class="font-medium">{hub.label}</span> + <span class="pv-chip shrink-0"> + {hub.projects.length} project{hub.projects.length === 1 ? '' : 's'} + </span> + </a> + </li> + )) + } + </ul> + + <section class="mt-16"> + <h2 class="text-2xl font-bold tracking-tight md:text-3xl">Categories</h2> + <p class="mt-2 max-w-2xl text-muted"> + The catalogue groups the same projects by what they are for. + </p> + <ul class="mt-6 flex flex-wrap list-none gap-2"> + { + categories.map((hub) => ( + <li> + <a href={hubHref(hub)} class="pv-chip no-underline"> + {hub.label} <span class="text-muted">({hub.projects.length})</span> + </a> + </li> + )) + } + </ul> + </section> + + <section class="mt-12 rounded-xl border border-border bg-surface p-6 md:p-8"> + <h2 class="text-xl font-semibold">Looking for the tools themselves?</h2> + <p class="mt-3 max-w-2xl text-sm text-muted"> + Open the <a href={withBase('/projects/')} class="pv-link">project catalogue</a>, the{' '} + <a href={withBase('/packages/')} class="pv-link">published packages</a>, or the{' '} + <a href={withBase('/use-cases/')} class="pv-link">use cases</a> that show what each project + does. + </p> + </section> + </div> +</SiteLayout> diff --git a/src/src/pages/use-cases/index.astro b/src/src/pages/use-cases/index.astro index 22a022f..00a591e 100644 --- a/src/src/pages/use-cases/index.astro +++ b/src/src/pages/use-cases/index.astro @@ -2,12 +2,25 @@ import SiteLayout from '~/layouts/SiteLayout.astro'; import UseCaseCard from '~/components/UseCaseCard.astro'; import UseCaseFilter from '~/components/islands/UseCaseFilter.tsx'; +import { defaultDocsChannel, readDocsManifest } from '~/lib/docs/aggregate'; import { loadProjects } from '~/lib/manifest/load'; import { AUDIENCES, AUDIENCE_LABELS } from '~/lib/manifest/schema'; import { SITE } from '~/lib/site'; import { withBase } from '~/lib/urls'; const projects = loadProjects().filter((project) => project.useCases.length > 0); +const docsManifest = readDocsManifest(); +/** + * Title of the documentation page a use case links to, so the link text names + * its destination ("Read Union design") instead of repeating one generic label. + */ +const docsTitlesFor = (projectId: string, slug: string | undefined): string | undefined => { + if (slug === undefined) { + return undefined; + } + const entry = docsManifest?.projects.find((project) => project.projectId === projectId); + return defaultDocsChannel(entry)?.pages.find((page) => page.slug === slug)?.title; +}; const entries = projects.flatMap((project) => project.useCases.map((useCase) => ({ useCase, @@ -61,6 +74,7 @@ const audiences = AUDIENCES.map((value) => ({ value, label: AUDIENCE_LABELS[valu projectName={project.name} projectId={project.id} docsBase={docsBase} + docsLabel={docsTitlesFor(project.id, useCase.docsPage)} /> </div> )) diff --git a/src/tests/dist/built-output.test.ts b/src/tests/dist/built-output.test.ts index f908055..f851bc9 100644 --- a/src/tests/dist/built-output.test.ts +++ b/src/tests/dist/built-output.test.ts @@ -717,3 +717,99 @@ describe('built documentation channels', () => { } }); }); + +describe('search metadata and browse surfaces (ADR 0015)', () => { + const active = loadProjects().filter((project) => project.status !== 'archived'); + const documented = active.filter((project) => project.docs); + + function titleOf(file: string): string { + return /<title>([^<]*)<\/title>/.exec(requireBuilt(file))?.[1] ?? ''; + } + + type CatalogueProject = ReturnType<typeof loadProjects>[number]; + + function requireProject(predicate: (candidate: CatalogueProject) => boolean): CatalogueProject { + const found = active.find(predicate); + if (!found) { + throw new Error('the catalogue must define a project that satisfies this test'); + } + return found; + } + + function requireDocumentedProject(): CatalogueProject { + const found = documented.find((candidate) => candidate.id === 'zodsharp') ?? documented[0]; + if (!found) { + throw new Error('the catalogue must document at least one project'); + } + return found; + } + + test('a documentation title names the project it documents, and the site', () => { + // `Unions | Purview Dev` is not findable; `… — Unions documentation | Purview Dev` is. + for (const project of documented) { + const title = titleOf(`docs/${project.id}/index.html`); + expect(title).toContain(project.name); + expect(title.endsWith('| Purview Dev')).toBe(true); + // The brand is appended once, not once per render. + expect(title.split('Purview Dev')).toHaveLength(2); + // And the title is what a result actually shows. + expect(title.length, `${title} (${title.length})`).toBeLessThanOrEqual(70); + } + }); + + test('the catalogue page title leads with the product, not the display name', () => { + const project = requireProject((candidate) => candidate.packages.length > 0); + const primary = project.packages.find((pkg) => pkg.primary) ?? project.packages[0]; + const title = titleOf(`projects/${project.id}/index.html`); + // The package id is what a reader searches for; the display name is not. + expect(title.startsWith(`${primary?.id} — `)).toBe(true); + expect(title).toContain('| Purview Dev'); + }); + + test('a project page is described as source code and as an application', () => { + const project = requireProject((candidate) => candidate.packages.length > 0); + const html = requireBuilt(`projects/${project.id}/index.html`); + expect(html).toContain('"@type":"SoftwareSourceCode"'); + expect(html).toContain('"@type":"SoftwareApplication"'); + expect(html).toContain('"@type":"BreadcrumbList"'); + }); + + test('a documentation page carries a TechArticle and a breadcrumb trail', () => { + const html = requireBuilt(`docs/${requireDocumentedProject().id}/index.html`); + expect(html).toContain('"@type":"TechArticle"'); + expect(html).toContain('"@type":"BreadcrumbList"'); + expect(html).toContain('"name":"Documentation"'); + }); + + test('a documentation page is an article to a social crawler, not a website', () => { + const html = requireBuilt(`docs/${requireDocumentedProject().id}/index.html`); + // The site sets no `og:type` globally, so Starlight's `article` survives. + expect(html).toMatch(/<meta property="og:type" content="article"\s*\/?>/); + expect(html).not.toMatch(/<meta property="og:type" content="website"\s*\/?>/); + }); + + test('the browse hubs are built', () => { + expect(existsSync(resolve(DIST, 'topics/index.html'))).toBe(true); + expect(existsSync(resolve(DIST, 'categories/index.html'))).toBe(true); + expect(existsSync(resolve(DIST, 'packages/index.html'))).toBe(true); + }); + + test('the catalogue links the browse surfaces', () => { + const html = requireBuilt('projects/index.html'); + expect(html).toContain('/topics/'); + expect(html).toContain('/categories/'); + expect(requireBuilt('index.html')).toContain('/topics/'); + }); + + test('a documentation page links the topics it carries', () => { + // Every hub that exists is reachable from the documentation as well as from + // the catalogue, which is what makes the docs pages a crawl path. + const topicsIndex = requireBuilt('topics/index.html'); + const href = /href="\/topics\/([a-z0-9-]+)\/"/.exec(topicsIndex)?.[1]; + expect(href).toBeDefined(); + const linked = documented.some((project) => + requireBuilt(`docs/${project.id}/index.html`).includes(`/topics/${href}/`), + ); + expect(linked).toBe(true); + }); +}); diff --git a/src/tests/unit/hubs.test.ts b/src/tests/unit/hubs.test.ts new file mode 100644 index 0000000..90462ee --- /dev/null +++ b/src/tests/unit/hubs.test.ts @@ -0,0 +1,198 @@ +import type { DocsManifest } from '../../src/lib/docs/aggregate'; +import type { ResolvedProject } from '../../src/lib/manifest/load'; +import type { ReleaseCacheData } from '../../src/lib/releases/types'; + +import { describe, expect, test } from 'bun:test'; + +import { DOCS_MANIFEST_SCHEMA } from '../../src/lib/docs/aggregate'; +import { + buildHubs, + canonicalTopic, + docsPageUrl, + topicHubHrefs, + topicHubPath, +} from '../../src/lib/hubs'; + +/** + * Hubs are derived, so the interesting behaviour is the *rules*: which tags earn + * a page, what a hub lists, and that the ordering is stable. + */ + +function project(id: string, overrides: Partial<ResolvedProject> = {}): ResolvedProject { + return { + id, + name: id.charAt(0).toUpperCase() + id.slice(1), + shortDescription: `${id} does a thing.`, + category: 'source-generation', + status: 'stable', + experimental: false, + order: 10, + repository: `purview-dev/${id}`, + packages: [], + related: [], + useCases: [], + skills: [], + assets: [], + acknowledgments: [], + ...overrides, + } as unknown as ResolvedProject; +} + +function releaseData(topics: Record<string, string[]>): ReleaseCacheData { + return { + repos: Object.fromEntries( + Object.entries(topics).map(([repository, values]) => [repository, { topics: values }]), + ), + } as unknown as ReleaseCacheData; +} + +function docsManifest(pages: Record<string, { slug: string; title: string }[]>): DocsManifest { + return { + schema: DOCS_MANIFEST_SCHEMA, + syncedAt: '2026-11-16T00:00:00Z', + releaseRetrievedAt: '2026-11-16T00:00:00Z', + projects: Object.entries(pages).map(([projectId, entries]) => ({ + projectId, + channels: [ + { + id: 'live' as const, + ref: 'main', + refKind: 'branch' as const, + version: null, + label: 'main', + default: true, + pages: entries.map((entry, index) => ({ + slug: entry.slug, + title: entry.title, + order: index, + sourcePath: `${entry.slug}.md`, + hash: `${entry.slug}-hash`, + })), + }, + ], + })), + }; +} + +const projects = [ + project('unions', { order: 20, category: 'source-generation' }), + project('zodsharp', { order: 10, category: 'validation' }), + project('solo', { order: 30, category: 'validation' }), +]; + +const data = releaseData({ + 'purview-dev/unions': ['csharp', 'union-types', 'value-types'], + 'purview-dev/zodsharp': ['csharp', 'validation'], + 'purview-dev/solo': ['lonely-topic'], +}); + +const manifest = docsManifest({ + unions: [ + { slug: 'index', title: 'Unions' }, + { slug: 'union-design', title: 'Union design' }, + ], + zodsharp: [{ slug: 'index', title: 'ZodSharp' }], +}); + +describe('buildHubs', () => { + const hubs = buildHubs(projects, data, manifest); + + test('publishes a hub only for a topic shared by enough projects', () => { + const slugs = hubs.topics.map((hub) => hub.slug).toSorted(); + // `union-types` and `validation` are each on one project only, so neither + // earns a page; `csharp` is shared and does. `lonely-topic` is not shared. + expect(slugs).toEqual(['csharp']); + expect(slugs).not.toContain('union-types'); + expect(slugs).not.toContain('lonely-topic'); + }); + + test('lists the projects the topic is on, in catalogue order', () => { + const csharp = hubs.topics.find((hub) => hub.slug === 'csharp'); + expect(csharp?.projects.map((entry) => entry.id)).toEqual(['zodsharp', 'unions']); + }); + + test('lists documentation pages of the tagged projects, without the landing page', () => { + const csharp = hubs.topics.find((hub) => hub.slug === 'csharp'); + expect(csharp?.pages.map((page) => page.url)).toEqual(['/docs/unions/union-design/']); + }); + + test('labels a topic with the words a reader types', () => { + const csharp = hubs.topics.find((hub) => hub.slug === 'csharp'); + expect(csharp?.label).toBe('C#'); + expect(csharp?.path).toBe('/topics/csharp/'); + expect(csharp?.title).toContain('C#'); + }); + + test('orders topics by how many projects they index', () => { + expect(hubs.topics[0]?.slug).toBe('csharp'); + }); + + test('builds a category hub from the same projects', () => { + // `source-generation` holds one project, so it is not published either. + const categories = hubs.categories.map((hub) => hub.slug).toSorted(); + expect(categories).toEqual(['validation']); + }); + + test('omits archived projects entirely', () => { + const allTopics = releaseData({ + 'purview-dev/unions': ['csharp', 'union-types', 'value-types'], + 'purview-dev/zodsharp': ['csharp', 'validation'], + 'purview-dev/solo': ['lonely-topic'], + 'purview-dev/dead': ['csharp'], + }); + const withArchived = buildHubs( + [...projects, project('dead', { status: 'archived', repository: 'purview-dev/dead' })], + allTopics, + manifest, + ); + const csharp = withArchived.topics.find((hub) => hub.slug === 'csharp'); + expect(csharp?.projects.map((entry) => entry.id)).not.toContain('dead'); + }); + + test('reports the topic spellings that have a hub, mapped to their href', () => { + const hrefs = topicHubHrefs(hubs); + expect(hrefs.get('csharp')).toBe('/topics/csharp/'); + // A repository that spells the topic `c-sharp` links the canonical hub. + expect(hrefs.get('c-sharp')).toBe('/topics/csharp/'); + expect(hrefs.has('lonely-topic')).toBe(false); + }); + + test('groups two spellings of one topic into a single hub', () => { + const spelledTwoWays = buildHubs( + projects, + releaseData({ + 'purview-dev/unions': ['c-sharp'], + 'purview-dev/zodsharp': ['csharp'], + }), + manifest, + ); + const hub = spelledTwoWays.topics.find((candidate) => candidate.slug === 'csharp'); + expect(hub?.projects.map((entry) => entry.id)).toEqual(['zodsharp', 'unions']); + expect(spelledTwoWays.topics.filter((candidate) => candidate.label === 'C#')).toHaveLength(1); + }); + + test('no two hubs share a title', () => { + const titles = [...hubs.topics, ...hubs.categories].map((hub) => hub.title); + expect(new Set(titles).size).toBe(titles.length); + }); + + test('topic paths are lowercase slugs', () => { + expect(topicHubPath('c-sharp')).toBe('/topics/c-sharp/'); + }); + + test('canonicalises the spellings of one topic', () => { + expect(canonicalTopic('c-sharp')).toBe('csharp'); + expect(canonicalTopic('CSharp')).toBe('csharp'); + // A distinct topic is left alone. + expect(canonicalTopic('net10')).toBe('net10'); + }); + + test('an index page addresses its folder, at any depth', () => { + expect(docsPageUrl('unions', 'index')).toBe('/docs/unions/'); + expect(docsPageUrl('astroc4', 'guide/index')).toBe('/docs/astroc4/guide/'); + expect(docsPageUrl('unions', 'union-design')).toBe('/docs/unions/union-design/'); + expect(docsPageUrl('zodsharp', 'schemas/custom-rules')).toBe( + '/docs/zodsharp/schemas/custom-rules/', + ); + }); +}); diff --git a/src/tests/unit/seo-check.test.ts b/src/tests/unit/seo-check.test.ts new file mode 100644 index 0000000..fc98fd1 --- /dev/null +++ b/src/tests/unit/seo-check.test.ts @@ -0,0 +1,95 @@ +import { describe, expect, test } from 'bun:test'; +import { join } from 'node:path'; + +import { + countH1, + decodeEntities, + distFileForPath, + extractCanonical, + extractJsonLd, + extractMeta, + extractTitle, +} from '../../scripts/check-seo'; + +/** + * The SEO check reads the built HTML, so its extractors are the part that must be + * right: a check that misreads a document either passes a broken page or fails a + * correct one. + */ + +const page = `<!doctype html><html><head> +<title>Union design — Unions documentation | Purview Dev + + + + +

Union design

Second

`; + +describe('title and canonical extraction', () => { + test('reads the title and decodes entities', () => { + expect(extractTitle(page)).toBe('Union design — Unions documentation | Purview Dev'); + }); + + test('returns null when there is no title', () => { + expect(extractTitle('')).toBeNull(); + }); + + test('reads the canonical href, not any other link', () => { + expect(extractCanonical(page)).toBe('https://purview.dev/docs/unions/union-design/'); + expect(extractCanonical('')).toBeNull(); + }); +}); + +describe('meta extraction', () => { + test('collects name attributes and decodes their content', () => { + const meta = extractMeta(page, 'name'); + expect(meta.get('description')).toBe('A & B description.'); + expect(meta.get('robots')).toBe('noindex'); + }); + + test('collects property attributes separately', () => { + const html = ''; + expect(extractMeta(html, 'property').get('og:type')).toBe('article'); + expect(extractMeta(html, 'name').size).toBe(0); + }); +}); + +describe('heading and structured-data extraction', () => { + test('counts every h1', () => { + expect(countH1(page)).toBe(2); + expect(countH1('

one

two

')).toBe(1); + }); + + test('parses JSON-LD and marks an unparseable block as null', () => { + expect(extractJsonLd(page)).toEqual([{ '@type': 'TechArticle', headline: 'Union design' }]); + expect(extractJsonLd('')).toEqual([null]); + expect(extractJsonLd('

none

')).toEqual([]); + }); +}); + +describe('object attribute extraction', () => { + test('keeps the order of the attributes in the tag', () => { + const html = ''; + expect(extractCanonical(html)).toBe('/a/'); + }); +}); + +describe('dist paths', () => { + test('maps a canonical path to its built file', () => { + // The function returns a real filesystem path, so the expectation is built the + // same way — asserting a literal `dist\index.html` only holds on Windows. + expect(distFileForPath('dist', '/')).toBe(join('dist', 'index.html')); + expect(distFileForPath('dist', '/about/')).toBe(join('dist', 'about', 'index.html')); + expect(distFileForPath('dist', '/docs/unions/union-design/')).toBe( + join('dist', 'docs', 'unions', 'union-design', 'index.html'), + ); + }); +}); + +describe('entity decoding', () => { + test('handles the entities the site emits', () => { + expect(decodeEntities('a & b <c> "d" 'e'')).toBe( + 'a & b "d" \'e\'', + ); + }); +}); diff --git a/src/tests/unit/seo.test.ts b/src/tests/unit/seo.test.ts new file mode 100644 index 0000000..25e8432 --- /dev/null +++ b/src/tests/unit/seo.test.ts @@ -0,0 +1,310 @@ +import { describe, expect, test } from 'bun:test'; + +import { readDocsManifest } from '../../src/lib/docs/aggregate'; +import { docSectionTrail } from '../../src/lib/docs/sidebar'; +import { getProjects, loadProjects } from '../../src/lib/manifest/load'; +import { + categoryPhrase, + docsDescription, + docsIndexTitle, + docsPageTitle, + firstSentence, + humaniseTag, + hubDescription, + hubTitle, + metaDescription, + productName, + projectPageDescription, + projectPageTitle, + truncate, +} from '../../src/lib/seo'; + +/** + * Search metadata is derived from the catalogue, so these tests assert the two + * things that make it worth deriving: a title leads with what a reader searches + * for, and a documentation page always names its project. + */ + +const unions = loadProjects().find((project) => project.id === 'unions'); +if (!unions) { + throw new Error('the catalogue must define unions for these tests'); +} + +describe('firstSentence', () => { + test('stops at the first sentence and drops its punctuation', () => { + expect(firstSentence('Enforce architecture policy as tests. Then more prose.')).toBe( + 'Enforce architecture policy as tests', + ); + }); + + test('returns the whole text when there is no terminator', () => { + expect(firstSentence('Typed Aspire resource kits')).toBe('Typed Aspire resource kits'); + }); + + test('collapses whitespace and handles empty input', () => { + expect(firstSentence(' a\n b ')).toBe('a b'); + expect(firstSentence(' ')).toBe(''); + }); +}); + +describe('truncate', () => { + test('prefers a sentence boundary inside the limit', () => { + const text = `${'a'.repeat(130)}. ${'b'.repeat(60)}`; + expect(truncate(text, 160)).toBe(`${'a'.repeat(130)}.`); + }); + + test('falls back to the last whole word', () => { + const text = 'alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo'; + const result = truncate(text, 40); + expect(result.endsWith('…')).toBe(true); + expect(result).not.toContain(' '); + expect(result.length).toBeLessThanOrEqual(41); + }); +}); + +describe('metaDescription', () => { + test('pads a short description with the supplied context', () => { + const result = metaDescription( + 'Zero-allocation schema validation for C#.', + 'A guide in the ZodSharp documentation — open-source .NET tooling from Purview Dev, with installation, use cases and examples on purview.dev.', + ); + expect(result).toContain('Zero-allocation schema validation'); + expect(result).toContain('ZodSharp documentation'); + expect(result.length).toBeGreaterThanOrEqual(120); + expect(result.length).toBeLessThanOrEqual(160); + }); + + test('never exceeds the maximum', () => { + const result = metaDescription('word '.repeat(80)); + expect(result.length).toBeLessThanOrEqual(160); + }); +}); + +describe('humaniseTag', () => { + test('maps the topic vocabulary a reader actually types', () => { + expect(humaniseTag('c-sharp')).toBe('C#'); + expect(humaniseTag('value-types')).toBe('value types'); + expect(humaniseTag('dotnet')).toBe('.NET'); + expect(humaniseTag('opentelemetry')).toBe('OpenTelemetry'); + expect(humaniseTag('net11')).toBe('.NET 11'); + }); +}); + +describe('categoryPhrase', () => { + test('turns a catalogue slug into words', () => { + expect(categoryPhrase('source-generation')).toBe('source generation'); + expect(categoryPhrase('something-new')).toBe('something new'); + }); +}); + +describe('project metadata', () => { + test('the product name is the primary package id', () => { + expect(productName(unions)).toBe('Purview.Unions'); + }); + + test('the title leads with the product and the searchable phrase', () => { + const title = projectPageTitle(unions); + expect(title.startsWith('Purview.Unions — ')).toBe(true); + // The searched words survive the budget: "C# 15 unions", not an abbreviation. + expect(title).toContain('C# 15 unions'); + expect(title.endsWith('| Purview Dev')).toBe(true); + expect(title.length).toBeLessThanOrEqual(70); + }); + + test('a project with a long name falls back to its category rather than overflowing', () => { + const telemetry = loadProjects().find((project) => project.id === 'telemetry-sourcegenerator'); + expect(telemetry).toBeDefined(); + const title = projectPageTitle(telemetry!); + // "Purview.Telemetry.SourceGenerator" is 34 characters on its own: the phrase + // cannot fit, so the title stays inside the budget without losing the product. + expect(title.startsWith('Purview.Telemetry.SourceGenerator — ')).toBe(true); + expect(title.length).toBeLessThanOrEqual(70); + }); + + test('a description mentions the project and stays within the limit', () => { + const description = projectPageDescription(unions); + // The first sentence is the substance; framework and topic detail is added + // while there is room, and the cut prefers a sentence end (see `truncate`). + expect(description).toContain('C#'); + expect(description.length).toBeGreaterThanOrEqual(70); + expect(description.length).toBeLessThanOrEqual(160); + }); +}); + +describe('documentation metadata', () => { + test('every title fits the budget and carries the brand', () => { + const title = docsPageTitle({ pageTitle: 'Union design', projectName: 'Unions' }); + expect(title).toBe('Union design — Unions documentation | Purview Dev'); + expect(title.length).toBeLessThanOrEqual(70); + }); + + test('the landing page title differs from the catalogue page title', () => { + const index = docsIndexTitle(unions); + expect(index).toContain('Unions documentation'); + expect(index).not.toBe(projectPageTitle(unions)); + expect(index.length).toBeLessThanOrEqual(70); + }); + + test('a folder is part of the title, because it is part of the URL', () => { + expect( + docsPageTitle({ + pageTitle: 'Custom rules', + projectName: 'ZodSharp', + sectionTrail: ['Schemas'], + }), + ).toBe('Schemas · Custom rules — ZodSharp documentation | Purview Dev'); + }); + + test('the section is dropped when the title would exceed the budget', () => { + const options = { pageTitle: 'Step cache tests', projectName: 'Telemetry SourceGenerator' }; + const withoutSection = docsPageTitle(options); + const withSections = docsPageTitle({ + ...options, + sectionTrail: ['Testing', 'Reference'], + }); + expect(withoutSection).toBe('Step cache tests — Telemetry SourceGenerator | Purview Dev'); + // The project name survives; the section and "documentation" do not. + expect(withSections).toBe(withoutSection); + expect(withSections.length).toBeLessThanOrEqual(70); + }); + + test('a short page title keeps the word "documentation"', () => { + expect(docsPageTitle({ pageTitle: 'Interop', projectName: 'Unions' })).toBe( + 'Interop — Unions documentation | Purview Dev', + ); + }); + + test('a second documentation version is distinguishable by title', () => { + const live = docsPageTitle({ pageTitle: 'Core concepts', projectName: 'ZodSharp' }); + const prerelease = docsPageTitle({ + pageTitle: 'Core concepts', + projectName: 'ZodSharp', + qualifier: 'Prerelease 3.0.0-prerelease.2', + }); + expect(prerelease).not.toBe(live); + expect(prerelease).toContain('Prerelease'); + expect(prerelease.length).toBeLessThanOrEqual(70); + }); + + test('the description names the page and the project', () => { + const description = docsDescription({ + summary: 'Tries each option in order.', + pageTitle: 'Union design', + projectName: 'Unions', + }); + expect(description).toContain('Union design'); + expect(description).toContain('Unions'); + expect(description.length).toBeLessThanOrEqual(160); + }); + + test('a passage that already fills a description is used as it stands', () => { + // 124 characters: long enough to be the description, so the context is not + // appended and the text is not cut. + const summary = 'word '.repeat(25).trim(); + const description = docsDescription({ + summary, + pageTitle: 'Union design', + projectName: 'Unions', + }); + expect(description).toBe(summary); + }); + + test('a long passage keeps its first sentence and fills the rest with context', () => { + // The aggregation extracts more of the first paragraph than a description + // holds (400 characters) precisely so this cut is available to it. + const sentence = `${'a'.repeat(88)}.`; + const summary = `${sentence} ${'b'.repeat(200)}`; + const description = docsDescription({ + summary, + pageTitle: 'Union design', + projectName: 'Unions', + }); + expect(description.startsWith(sentence)).toBe(true); + expect(description).toContain('Unions'); + expect(description.length).toBeLessThanOrEqual(160); + }); +}); + +describe('the title policy over the real catalogue', () => { + const manifest = readDocsManifest(); + const projects = getProjects().filter((project) => project.docs && project.status !== 'archived'); + + /** Every title the site would publish for documentation, as (title, project) pairs. */ + function samples(): { title: string; projectName: string }[] { + const result: { title: string; projectName: string }[] = []; + for (const project of projects) { + const entry = manifest?.projects.find((candidate) => candidate.projectId === project.id); + const channels = entry?.channels.length ? entry.channels : [undefined]; + for (const channel of channels) { + // The landing page carries the version; a deep page carries the family, + // so a long version label cannot push the page title out. + const indexQualifier = channel && !channel.default ? channel.label : undefined; + const pageQualifier = channel && !channel.default ? 'Prerelease' : undefined; + result.push({ + title: docsIndexTitle(project, { qualifier: indexQualifier }), + projectName: project.name, + }); + for (const page of channel?.pages ?? []) { + result.push({ + title: docsPageTitle({ + pageTitle: page.title, + projectName: project.name, + sectionTrail: docSectionTrail(page.slug), + qualifier: pageQualifier, + }), + projectName: project.name, + }); + } + } + } + return result; + } + + const all = samples(); + + test('there is something to check', () => { + expect(projects.length).toBeGreaterThan(0); + expect(all.length).toBeGreaterThan(50); + }); + + test('every title fits what a search result shows', () => { + for (const { title } of all) { + expect(title.length, `${title} (${title.length})`).toBeLessThanOrEqual(70); + } + }); + + test('every catalogue page title fits too', () => { + for (const project of getProjects().filter((candidate) => candidate.status !== 'archived')) { + const title = projectPageTitle(project); + expect(title.length, `${title} (${title.length})`).toBeLessThanOrEqual(70); + // Whatever is trimmed, the product name is what a reader searches for. + expect(title, title).toContain(productName(project)); + } + }); + + test('every title names the project it documents', () => { + for (const { title, projectName } of all) { + expect(title, title).toContain(projectName); + } + }); +}); + +describe('hub metadata', () => { + test('titles describe the collection and stay short', () => { + expect(hubTitle('union types', 'topic')).toBe('Union types — Purview .NET projects and guides'); + expect(hubTitle('source generation', 'category')).toBe( + 'Source generation — Purview .NET projects', + ); + }); + + test('descriptions name the projects the hub indexes', () => { + const description = hubDescription({ + label: 'C#', + kind: 'topic', + projectNames: ['Unions', 'ZodSharp'], + }); + expect(description).toContain('Unions'); + expect(description).toContain('ZodSharp'); + expect(description.length).toBeLessThanOrEqual(160); + }); +});