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 Canonical Permalinks

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.