astro-website/openspec/specs/blog-section-surface/spec.md

Purpose

Expose a blog section on the site backed by cached WordPress content, including listing, detail pages, and category browsing.

ADDED Requirements

Requirement: Primary navigation entry

The site MUST add a header navigation link to the blog index at /blog labeled "Blog".

Scenario: Blog link in header

• WHEN a user views any page
• THEN the header navigation includes a "Blog" link that navigates to /blog

Requirement: Blog index listing (posts)

The site MUST provide a blog index page at /blog that lists WordPress posts as cards containing:

• featured image (when available)
• title
• excerpt/summary
• publish date

The listing MUST be ordered by publish date descending (newest first).

The card MUST render a footer row that includes:

• publish date on the left
• views on the right when available (if views are not provided by the dataset, the card MUST omit views without breaking layout)
• a content source label (e.g., blog)

Each post card MUST be instrumented with Umami Track Events data attributes and MUST include at minimum:

• data-umami-event
• data-umami-event-target_id
• data-umami-event-placement
• data-umami-event-target_url

Scenario: Blog index lists posts

• WHEN the cached WordPress dataset contains posts
• THEN /blog renders a list of post cards ordered by publish date descending

Scenario: Blog post card click is tracked

• WHEN a user clicks a blog post card on /blog
• THEN the click emits an Umami event with target_id, placement, and target_url

Scenario: Blog post card layout is standardized

• WHEN /blog renders a blog post card
• THEN the card shows featured image (when available), title, trimmed excerpt, and a footer bar containing date, optional views, and a source label

Requirement: Blog post detail

The site MUST provide a blog post detail page for each WordPress post that renders:

• title
• publish date
• featured image (when available)
• full post content

Scenario: Post detail renders

• WHEN a user navigates to a blog post detail page
• THEN the page renders the full post content from the cached WordPress dataset

Requirement: WordPress pages support

The blog section MUST support WordPress pages by rendering page detail routes that show:

• title
• featured image (when available)
• full page content

Scenario: Page detail renders

• WHEN a user navigates to a WordPress page detail route
• THEN the page renders the full page content from the cached WordPress dataset

Requirement: Category-based secondary navigation

The blog section MUST render a secondary navigation under the header derived from the cached WordPress categories.

Selecting a category MUST navigate to a category listing page showing only posts in that category.

Each secondary navigation link MUST be instrumented with Umami Track Events data attributes and MUST include at minimum:

• data-umami-event
• data-umami-event-target_id
• data-umami-event-placement
• data-umami-event-target_url

Scenario: Category nav present

• WHEN the cached WordPress dataset contains categories
• THEN the blog section shows a secondary navigation with those categories

Scenario: Category listing filters posts

• WHEN a user navigates to a category listing page
• THEN only posts assigned to that category are listed

Scenario: Category nav click is tracked

• WHEN a user clicks a category link in the blog secondary navigation
• THEN the click emits an Umami event with target_id, placement, and target_url

Requirement: Graceful empty states

If there are no WordPress posts available, the blog index MUST render a non-broken empty state and MUST still render header/navigation.

Scenario: No posts available

• WHEN the cached WordPress dataset contains no posts
• THEN /blog renders a helpful empty state