astro-website/openspec/changes/blogs-section/design.md

Context

The site is currently a static Astro build served via nginx. Content is populated by a build-time fetch step (site/scripts/fetch-content.ts) that writes a repo-local cache file consumed by the Astro pages/components.

We want to add a new Blog section backed by a WordPress site via the wp-json REST APIs, including:

• a primary header nav link (/blog)
• blog listing pages (cards with featured image, title, excerpt)
• blog detail pages (full content)
• a blog-only secondary navigation based on WordPress categories
• support for both WordPress posts and pages

Goals / Non-Goals

Goals:

• Add /blog with a listing of WordPress posts rendered as static HTML at build time.
• Add detail pages for WordPress posts and pages, rendered as static HTML at build time.
• Add category-based browsing within the Blog section (secondary navigation + category listing pages).
• Use environment variables for WordPress configuration (site URL and credentials) and fetch via wp-json.
• Keep pages indexable and included in sitemap output.

Non-Goals:

• Real-time updates without rebuilds (v1 remains build-time fetched).
• Implementing “like” storage in WordPress or a database (nice-to-have can be a simple outbound share action later).
• Full WordPress theme parity (we render a simplified reading surface).

Decisions

• Decision: Build-time ingestion into the existing content cache.

  • Rationale: Matches the current architecture (cache file + static build), keeps the site fast and crawlable, and avoids introducing a runtime server layer.
  • Alternative: Client-side fetch from WP directly. Rejected for SEO and performance (would rely on client rendering and adds CORS/auth complexity).

• Decision: Prefer WordPress Application Passwords over raw user passwords (if possible).

  • Rationale: Application passwords are the standard WP approach for API access and can be revoked without changing the user login password.
  • Alternative: Basic auth with username/password. Allowed if that’s what your WP setup supports, but we should treat credentials as secrets in .env.

• Decision: Normalize WordPress content into a small internal schema.

  • Rationale: Keeps UI components simple and consistent with existing content rendering patterns (cards + detail pages).
  • Implementation: Add a wordpress source to the cache schema, with fields for id, slug, kind (post|page), title, excerpt, contentHtml, featuredImageUrl, publishedAt, updatedAt, categories.

• Decision: Route structure.

  • Rationale: Keep URLs clear and stable.
  • Proposed:
    • /blog (latest posts)
    • /blog/category/<slug> (posts in category)
    • /blog/post/<slug> (post detail)
    • /blog/page/<slug> (page detail)

Risks / Trade-offs

• [Risk] WP API rate limits / downtime break the build. → Mitigation: Cache last-known-good content.json; on fetch failure, retain existing cache and log errors.
• [Risk] WordPress HTML content can contain unexpected markup or scripts. → Mitigation: Render server-side as HTML but sanitize or strip scripts; document allowed HTML subset.
• [Risk] Auth method differs per WP hosting. → Mitigation: Support both public endpoints for reading (preferred) and authenticated requests when needed; keep config flexible.