wp-block-pattern-gotchas

Diagnose silent failures in WordPress block theme patterns, templates, and layout attributes.

Updated Jul 22, 2026
One-click install
npx skills add https://github.com/lightspeedwp/spotlight-theme-2026 --skill wp-block-pattern-gotchas-lightspeedwp
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: wp-block-pattern-gotchas
Source: https://github.com/lightspeedwp/spotlight-theme-2026/tree/main/.agents/skills/wp-block-pattern-gotchas
Command: npx skills add https://github.com/lightspeedwp/spotlight-theme-2026 --skill wp-block-pattern-gotchas-lightspeedwp

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? WordPress block patterns and templates often fail silently — no errors, no exceptions — when layout types, spacing attributes, or pattern references behave differently than expected, costing hours of debugging. This Skill provides a checklist of verified core behaviors so you can avoid or quickly diagnose these pitfalls before writing or debugging pattern markup. ## Core Features & Use Cases - Layout Pitfall Reference: Documents the real accepted values for layout.type, the cross-fill behavior of contentSize/wideSize, and why margin and blockGap are unreliable inside default/constrained layouts. - Pattern Context Diagnosis: Explains why wp:pattern references lose ambient block context inside query loops and how to fix it with PHP require or expanded markup in .html templates. - Serialization and Validation Traps: Covers __experimentalSkipSerialization attributes, bare HTML tags breaking block validation, DB-stored overrides shadowing file edits, caching layers masking changes, and php -l missing dangling require() calls. - Use Case: A pattern renders empty on the front end but passes a CLI do_blocks() test — consult this Skill to identify the context-loss pitfall and inline the referenced pattern correctly. ## Quick Start Review this checklist before writing or debugging any WordPress block pattern, template, or template part to catch silent-failure pitfalls early.

Frequently Asked Questions about wp-block-pattern-gotchas

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my WordPress block pattern render empty on the front end?▼

A wp:pattern reference renders through a fresh do_blocks() call with no context, so blocks needing postId inside a query loop get nothing. Inline the pattern with PHP require or expand its markup directly in .html templates.

What values does the WordPress layout.type attribute accept?▼

The layout.type attribute only accepts "default", "constrained", "flex", or "grid". There is no "flow" value; use "default" for plain vertical stacking with no special layout behavior.

Why is my block style attribute missing from the rendered HTML?▼

The block's block.json may mark that support as __experimentalSkipSerialization, so the attribute shows in the editor but is excluded from saved output. Use enqueued CSS targeting the block's rendered classes instead.

Why do WordPress pattern file edits not show on the live site?▼

A Site Editor edit creates a database copy that overrides the theme file, and caching layers like WP Super Cache or OPcache can mask changes. Reset the template in the editor and clear each cache layer.

How do I fix spacing not working inside constrained layout groups?▼

WordPress layout support forces margin-block-end: 0 on children of default/constrained containers, overriding margins and blockGap. Use style.spacing.padding instead, which always serializes without such overrides.