SEO and metadata

Metadata contract

src/layouts/Layout.astro is the canonical metadata wrapper for normal pages.

It accepts optional props:

• title
• description
• keywords
• image
• canonicalUrl
• type (website or article)

Layout.astro computes defaults and passes normalized values into @cosmos/ui-astro/layout/SeoHead.astro.

Defaults and canonical origin

• Site defaults are defined in SITE_CONFIG inside Layout.astro.
• siteOrigin precedence: Astro.site?.origin -> PUBLIC_SITE_URL -> hardcoded production origin.
• If a page does not pass metadata props, layout defaults are used.

Page authoring guidance

• Use Layout for public routes unless there is a deliberate exception.
• Set explicit title and description for non-generic pages.
• Use canonicalUrl override only when a route needs non-default canonical behavior.

Sitemap ownership

• src/pages/sitemap.xml.ts owns generated XML.
• Route entries are explicit in SITEMAP_ENTRIES; new important routes are not auto-added.
• lastmod is generated at request time.

Robots ownership

• src/pages/robots.txt.ts owns robots output.
• It emits a Sitemap: URL based on Astro site or environment fallback.

Change checklist

• New indexable route: update SITEMAP_ENTRIES in sitemap.xml.ts.
• Canonical/domain change: verify astro.config.mjs site, PUBLIC_SITE_URL, and layout origin fallback.
• Any metadata contract change in shared SeoHead: verify every page still composes correctly via Layout.