Gutenberg Case Study Blocks Plan

Goal

Enable case study creators to build rich pages in WordPress Gutenberg while the Astro site renders those blocks as high-fidelity static pages.

Non-goals

• No full Gutenberg parity in phase 1.
• No dependency on front-end WordPress rendering at runtime.
• No shipping untrusted raw HTML without sanitization.

Proposed architecture

1. Authors create case studies in WordPress using a constrained block set.
2. Build step fetches post JSON from WP REST API, including content.rendered and block metadata when available.
3. Astro parses Gutenberg block structure into an internal AST.
4. Supported blocks map to typed Astro components.
5. Unsupported blocks fall back to safe HTML rendering with warning logs.
6. Build produces static pages and a support report for editorial + dev teams.

Content model in WordPress

1. Create a dedicated case study post type (case_study) with:

• title
• slug
• hero media
• summary/excerpt
• sector/client taxonomy
• project metrics (repeatable key/value)
• related work links

2. Editorial constraints:

• Provide a “Bozboz Case Study” block pattern set.
• Restrict allowed blocks in case study editor.
• Prefer semantic blocks over freeform HTML.

Block support matrix (phase-based)

Phase 1: core essentials

• core/paragraph
• core/heading
• core/list
• core/image
• core/gallery
• core/quote
• core/separator
• core/buttons + core/button
• core/spacer
• core/group
• core/columns + core/column
• core/embed (whitelist providers)

Phase 2: richer storytelling

• core/pullquote
• core/table
• core/details
• core/media-text
• custom metric cards block
• custom timeline/process block

Phase 3: advanced campaign layouts

• curated custom interactive blocks
• optional animation metadata fields for Astro/GSAP behavior

Rendering strategy in Astro

1. Add a block parser in the content pipeline:

• input: WP post content + block metadata
• output: typed CaseStudyBlock[]

2. Create block components, e.g.:

• src/components/blocks/BlockParagraph.astro
• src/components/blocks/BlockImage.astro
• src/components/blocks/BlockColumns.astro
• etc.

3. Add a block renderer switch:

• maps blockName -> Astro component
• logs unsupported blocks to build output
• preserves author intent where possible (alignment, spacing, caption, link behavior)

4. Sanitization and safety:

• sanitize fallback HTML
• whitelist iframe/embed providers
• strip inline script/style payloads

Editorial experience

1. Add a Gutenberg “Case Study Starter” pattern with:

• hero intro
• challenge/approach/outcome sections
• metrics row
• CTA block

2. Add docs for creators:

• which blocks are supported
• how each block appears on static site
• what to avoid in phase 1

3. Add preview QA checklist in editorial workflow.

Build and QA workflow

1. During npm run build, emit:

• unsupported block list per slug
• warning count per post
• summary table in console

2. Add visual regression snapshots for top case studies.

3. Add schema tests:

• block parser unit tests
• component snapshot tests
• sanitization tests

URL and routing proposal

• Listing page: /work/
• Case study pages: /work/{slug}/
• Keep current external fallback links while migrating entries incrementally.

Migration plan

1. Pilot with 2 case studies.
2. Freeze block set for phase 1.
3. Build + QA + editorial review.
4. Migrate remaining case studies in batches.
5. Track unsupported block occurrences and prioritize next block implementations.

Risks and mitigations

1. Risk: editorial uses unsupported blocks.

• Mitigation: allowed-block restrictions + build warnings + docs.

2. Risk: design drift from authored content.

• Mitigation: pattern library + component parity reviews.

3. Risk: embed/security issues.

• Mitigation: strict sanitization and provider allowlist.

Success criteria

1. Authors can publish case studies without developer intervention.
2. 90%+ of case study block usage supported in phase 1+2.
3. Zero runtime dependency on WordPress rendering.
4. Lighthouse and accessibility scores stay within current site targets.

Suggested implementation tasks

1. Define case_study post type + taxonomies in WP.
2. Add Gutenberg allowed-block policy for case studies.
3. Build parser + AST types in src/lib/wp.ts pipeline.
4. Implement phase 1 block components.
5. Add build warnings/reporting for unsupported blocks.
6. Pilot on 2 real case studies and iterate.

Current scaffold in this repo

The following foundation has already been added:

1. Parser + support matrix:

• src/lib/gutenberg.ts

2. Renderer + JS enhancements:

• src/components/blocks/GutenbergRenderer.astro
• src/components/blocks/GutenbergEnhancements.astro

3. Core block styling layer:

• src/styles/blocks/_gutenberg-core.scss

4. Sandbox route for testing block rendering:

• /ideas/gutenberg-sandbox/