v5.12.0 27 February 2026 Feature Improvement

Canonical Release Pages, RSS Canonicalisation & Description Enrichment

Why This Matters

The changelog is one of the most content-rich pages on the marketing site, with 111 releases documented across four major versions. Until now, every release existed as a section inside a single page — invisible to search engines, unshareable as individual documents, and lacking per-release metadata.

This release promotes each changelog entry from a page fragment to a first-class document with its own canonical URL, structured data, and link preview. It also establishes the description field as a forward-looking enrichment for RSS subscribers and search engines.

Canonical Per-Release Pages

Every changelog entry now renders as its own page at /changelog/{releaseSlug}/.

  • 111 release pages generated at build time Each entry in the changelog content collection produces a static HTML page with full rendered markdown content, breadcrumb navigation, and consistent typography matching the changelog index.

  • JSON-LD structured data Every release page includes a SoftwareSourceCode schema with version, date, author, and publisher metadata. We use SoftwareSourceCode to model versioned releases as indexable software updates; this is stable and machine-readable across search surfaces.

  • OpenGraph and meta tags Each page has distinct og:title, og:description, og:url, and article:published_time tags, enabling rich link previews in Slack, iMessage, Twitter/X, and other sharing surfaces.

  • Build-time collision guard getStaticPaths() detects duplicate slugs and fails the build rather than silently overwriting pages. Invalid data never deploys.

  • Trailing slash standardisation Canonical URLs use a trailing slash to match site routing and avoid duplicate indexable variants.

Slug Infrastructure

  • releaseSlug frontmatter field Each entry has a URL-safe slug derived from version number and title keywords. Named releaseSlug (not slug) to avoid collision with Astro’s reserved slug property on content collection entries.

  • Backfill automation add-changelog-slugs.mjs generated slugs for all 111 existing entries in a single run. The script is idempotent — safe to run multiple times, skips entries that already have a releaseSlug.

  • Schema validation The content schema enforces slug format (^\d+-\d+-\d+(-[a-z0-9]+)*$) and date format (YYYY-MM-DD) at build time. Malformed frontmatter fails the build.

The URL segment is referred to as slug in routing ([slug].astro) and is sourced from the releaseSlug frontmatter field.

RSS entries now resolve to stable, dereferenceable permalinks instead of fragment-based anchors.

  • Canonical <link> and <guid> Both now point to /changelog/{releaseSlug}/ instead of /changelog/#vX.Y.Z, giving each RSS item a permanent, dereferenceable URL with isPermaLink="true".

  • Per-item descriptions Every RSS item now includes a <description> element. New entries use the enriched description frontmatter field; existing entries fall back to a title-based summary.

Description Enrichment

A new optional description frontmatter field provides a 1–2 sentence summary of what changed and why.

  • Three audiences served simultaneously The description appears in RSS feed readers, search engine result pages (as meta description), and link previews when sharing release URLs.

  • Forward-looking adoption The field is optional to avoid breaking the 111 existing entries. All new releases from v5.12.0 onwards include an enriched description that adds signal beyond the title.

  • Preview-safe constraint description is capped at 200 characters to remain readable in RSS readers and link previews.

Changelog Index Wiring

The changelog index page at /changelog/ now links each release through to its canonical page.

  • Version number links The v5.11.0 version badge now navigates to /changelog/5-11-0-speydocs-production-gold-search-hardening-footer-redesign/ instead of self-referencing with a #v anchor.

  • Title links Release titles are now clickable, navigating to the same canonical page with a subtle hover transition.

  • Legacy anchors preserved Each <article> retains its id="v5.11.0" anchor, so existing external links and in-page scrolling continue to work.

Compatibility

  • Legacy fragment URLs (/changelog/#vX.Y.Z) continue to resolve via preserved <article id="vX.Y.Z"> anchors on the index page.
  • Canonical URLs (/changelog/{releaseSlug}/) are now the preferred share and RSS targets.

Operational Impact

  • 111 individually indexable release pages with distinct OpenGraph previews
  • JSON-LD SoftwareSourceCode structured data on every release page
  • RSS items with stable canonical permalinks and meaningful descriptions
  • RSS <description> derived from frontmatter, improving feed readability without requiring click-through
  • Build-time validation prevents malformed slugs, dates, or duplicate routes from deploying
  • Zero breaking changes to existing changelog content or external links

Files Changed

Backend: None

Marketing site (speybooks.com):

  • src/content/config.ts

    • Added description (optional string, max 200 chars)
    • Added releaseSlug (optional, regex-validated)
    • Added date format validation (YYYY-MM-DD)

  • src/pages/changelog/[slug].astro — new file

    • Per-release page template with JSON-LD, OpenGraph, tag badges
    • Build-time slug collision detection
    • Light theme typography matching changelog index

  • src/pages/changelog/rss.xml.ts

    • Canonical slug URLs for <link> and <guid>
    • <description> from frontmatter with title-based fallback

  • src/pages/changelog/index.astro

    • Version and title now link to canonical release pages
    • Added getSlug helper for releaseSlug resolution

  • add-changelog-slugs.mjs — new file

    • Backfill script: generated releaseSlug for 111 existing entries

  • src/content/changelog/*.md

    • All 111 entries updated with releaseSlug field

This release establishes the changelog as a versioned document system — each release independently addressable, machine-readable, and built to scale with the platform.