astro-website/openspec/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).

The deployed static server MUST serve these pages successfully for both trailing-slash and non-trailing-slash requests when a directory-based index.html exists (for example, /videos and /videos/ MUST both resolve to the videos page).

Scenario: Crawling the home page

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

Scenario: Direct request without trailing slash

• WHEN a user requests /videos (no trailing slash)
• THEN the server returns the videos page HTML and does not respond with 404

Scenario: Direct request with trailing slash

• WHEN a user requests /videos/ (with trailing slash)
• THEN the server returns the videos page HTML and does not respond with 404

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-index.xml enumerating indexable pages (and/or referencing sitemap shards)
• robots.txt that allows indexing of indexable pages

The sitemap MUST include the blog surface routes:

• /blog
• blog post detail routes
• blog page detail routes
• blog category listing routes

robots.txt MUST reference the sitemap using an absolute URL for the production domain.

Scenario: Sitemap index is available

• WHEN a crawler requests /sitemap-index.xml
• THEN the server returns an XML sitemap index (or sitemap) listing /, /videos, /podcast, /about, and /blog

Scenario: Blog URLs appear in sitemap

• WHEN WordPress content is available in the cache at build time
• THEN the generated sitemap includes the blog detail URLs for those items

Scenario: Robots references sitemap with absolute URL

• WHEN a crawler requests /robots.txt
• THEN the response contains a Sitemap: line with an absolute URL to /sitemap-index.xml

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

Requirement: Organization and website structured data

The home page SHOULD include JSON-LD structured data for the site and its owner/organization.

If present, the JSON-LD MUST be valid JSON and MUST use a recognized schema type.

Scenario: Home page includes valid JSON-LD

• WHEN a crawler requests /
• THEN the HTML contains a JSON-LD script tag that parses as valid JSON