astro-website/openspec/changes/archive/2026-02-10-dynamic-homepage-social-acquisition/specs/seo-content-surface/spec.md

ADDED Requirements

Requirement: Indexable pages

The site MUST provide indexable HTML pages for:

• home (/)
• videos (/videos)
• podcast (/podcast)
• about (/about)

These pages MUST be server-rendered or statically generated HTML suitable for search engine crawling (not client-rendered only).

Scenario: Crawling the home page

• WHEN a crawler requests /
• THEN the server returns an HTML document containing the homepage content modules and metadata

Requirement: Metadata and canonical URLs

Each indexable page MUST define:

• a document title
• a meta description
• a canonical URL

Scenario: Page metadata is present

• WHEN a crawler requests /videos
• THEN the HTML contains a <title>, a meta description, and a canonical URL for /videos

Requirement: Social sharing cards

The site MUST provide Open Graph and Twitter card metadata for indexable pages so shared links render a preview.

Scenario: Sharing the home page

• WHEN a social crawler requests /
• THEN the response includes Open Graph and Twitter card tags with a title, description, and image when available

Requirement: Sitemap and robots

The site MUST provide:

• sitemap.xml enumerating indexable pages
• robots.txt that allows indexing of indexable pages

Scenario: Sitemap is available

• WHEN a crawler requests /sitemap.xml
• THEN the server returns an XML sitemap listing /, /videos, /podcast, and /about

Requirement: Structured data

The site MUST support structured data (JSON-LD) for Video and Podcast content when detail pages exist, and MUST ensure the JSON-LD is valid JSON.

Scenario: Video structured data present

• WHEN a video detail page exists and is requested
• THEN the HTML includes JSON-LD describing the video using a recognized schema type