ADR 0060 — The homepage document lives at one URL

Cusp lets an editor pick any published Page as the site homepage by setting site.homepage_page_slug. The public render handler then serves that page's HTML at /. The bug this decision closes: the same page was also still reachable at its own permalink (for example /welcome), so identical content was served at both / and /welcome, each declaring itself canonical. Both URLs were also emitted in sitemap.xml, and the homepage page appeared as an item in the RSS feed. That is textbook duplicate content — search engines split ranking signals across the two URLs, and the feed carries an entry that is really the site's front door.

Context

The homepage-resolution rule already existed (documented in the rendering and cache architecture note, /architecture/rendering-and-cache): if site.homepage_page_slug resolves to a published Page, render it at /; otherwise fall back to the recent-posts listing. What was missing was the corollary — once a page is promoted to /, its own permalink is no longer a distinct address for that content. A recent change (fix(public): canonicalise URL shape) established that the public handler owns URL canonicalisation and 301s to the single correct form before any cache or R2 lookup. This decision extends that same principle to the homepage case.

The decision

• A GET/HEAD request for the homepage page's own permalink returns a 301 to /, preserving the query string. The check runs on the cache-miss path only — after the edge-cache lookup, before the R2 lookup — so the common cache hit never pays the extra settings read. It fires only when a homepage slug is set and the chosen page is actually published (serving at /); an unpublished configured page 404s at its permalink as before rather than redirecting to a recent-posts home.
• sitemap.xml lists the homepage page only as the / entry. Its own permalink is dropped when the sitemap is regenerated, so the page appears exactly once.
• The RSS feed never includes the homepage page as an item. The exclusion happens in the same artefact-regeneration pass that builds the sitemap, keyed on the page's permalink.

Consequences

• The homepage content has exactly one canonical URL (/) across the rendered page, the sitemap, and the feed. No duplicate-content penalty and no split ranking signals.
• An inbound link to the old /welcome permalink still works — it 301s to /, passing link equity along and keeping bookmarks valid.
• The redirect adds one settings read on cache-miss requests. Cache hits — the overwhelming majority of public traffic — are unaffected. Swapping which page is the homepage bumps the cache epoch (a settings change), so any previously cached response for the old permalink is invalidated automatically.
• The behaviour is exercised end-to-end: the redirect in the public-render homepage integration tests, and the sitemap/feed exclusion in the unpublish-pipeline artefact tests.