references/block-markup-reference.md

Block Markup Reference

Comment Syntax

WordPress blocks are serialized as HTML comments with JSON attributes.

<!-- wp:block-name {"attr":"value"} -->
<div class="wp-block-block-name">Inner content</div>
<!-- /wp:block-name -->

<!-- wp:block-name {"attr":"value"} /-->  (self-closing, no inner content)

Rules:

Opening tag: 
Core blocks omit namespace:  (not core/heading)
JSON must be valid — no trailing commas, strings double-quoted
Self-closing blocks (spacer, separator, image with no caption): end with /-->
Every opening comment must have a matching closing comment

Most-Used Blocks in Patterns

Layout Blocks

Group — primary container, supports all layout types:

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- inner blocks -->
</div>
<!-- /wp:group -->

Layout types:

{"type":"constrained"} — centered with max-width (default for sections)
{"type":"constrained","contentSize":"800px","wideSize":"1200px"} — custom widths
{"type":"flex","flexWrap":"nowrap"} — horizontal row
{"type":"flex","orientation":"vertical"} — vertical stack
{"type":"grid","columnCount":3} — CSS grid with fixed columns
{"type":"grid","minimumColumnWidth":"250px"} — responsive auto-fill grid

Tag name override: {"tagName":"section"}, {"tagName":"header"}, {"tagName":"footer"}

Columns / Column:

<!-- wp:columns -->
<div class="wp-block-columns">
  <!-- wp:column {"width":"66.66%"} -->
  <div class="wp-block-column" style="flex-basis:66.66%">
    <!-- inner blocks -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column {"width":"33.33%"} -->
  <div class="wp-block-column" style="flex-basis:33.33%">
    <!-- inner blocks -->
  </div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->

Content Blocks

Heading:

<!-- wp:heading {"level":2,"fontSize":"x-large"} -->
<h2 class="wp-block-heading has-x-large-font-size">Heading text</h2>
<!-- /wp:heading -->

Paragraph:

<!-- wp:paragraph {"fontSize":"medium","textColor":"contrast"} -->
<p class="has-contrast-color has-text-color has-medium-font-size">Body text</p>
<!-- /wp:paragraph -->

Image:

<!-- wp:image {"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full">
  <img src="https://example.com/image.jpg" alt="Descriptive alt text"/>
</figure>
<!-- /wp:image -->

Cover:

<!-- wp:cover {"url":"https://example.com/bg.jpg","dimRatio":60,"overlayColor":"contrast","minHeight":500,"minHeightUnit":"px","layout":{"type":"constrained"}} -->
<div class="wp-block-cover" style="min-height:500px">
  <span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-60 has-background-dim"></span>
  <img class="wp-block-cover__image-background" alt="" src="https://example.com/bg.jpg" data-object-fit="cover"/>
  <div class="wp-block-cover__inner-container">
    <!-- inner blocks -->
  </div>
</div>
<!-- /wp:cover -->

Buttons / Button:

<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons">
  <!-- wp:button {"backgroundColor":"primary","textColor":"base"} -->
  <div class="wp-block-button"><a class="wp-block-button__link has-base-color has-primary-background-color has-text-color has-background wp-element-button">Click me</a></div>
  <!-- /wp:button -->
  <!-- wp:button {"className":"is-style-outline"} -->
  <div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">Secondary</a></div>
  <!-- /wp:button -->
</div>
<!-- /wp:buttons -->

Spacer:

<!-- wp:spacer {"height":"var:preset|spacing|50"} -->
<div style="height:var(--wp--preset--spacing--50)" aria-hidden="true" class="wp-block-spacer"></div>
<!-- /wp:spacer -->

Separator:

<!-- wp:separator {"backgroundColor":"contrast","className":"is-style-wide"} -->
<hr class="wp-block-separator has-text-color has-contrast-color has-alpha-channel-opacity has-contrast-background-color has-background is-style-wide"/>
<!-- /wp:separator -->

Media & Text:

<!-- wp:media-text {"mediaPosition":"right","mediaType":"image","mediaWidth":40} -->
<div class="wp-block-media-text has-media-on-the-right is-stacked-on-mobile" style="grid-template-columns:auto 40%">
  <div class="wp-block-media-text__content">
    <!-- inner blocks -->
  </div>
  <figure class="wp-block-media-text__media">
    <img src="https://example.com/image.jpg" alt="Description"/>
  </figure>
</div>
<!-- /wp:media-text -->

Query Loop (post listing):

<!-- wp:query {"queryId":0,"query":{"perPage":3,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","inherit":false}} -->
<div class="wp-block-query">
  <!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
    <!-- wp:post-featured-image {"isLink":true} /-->
    <!-- wp:post-title {"isLink":true,"fontSize":"large"} /-->
    <!-- wp:post-excerpt {"excerptLength":20} /-->
  <!-- /wp:post-template -->
</div>
<!-- /wp:query -->

Style Attribute Structure

The style attribute holds custom values (not preset slugs):

{
  "style": {
    "spacing": {
      "padding": {"top":"var:preset|spacing|50","right":"var:preset|spacing|50","bottom":"var:preset|spacing|50","left":"var:preset|spacing|50"},
      "margin": {"top":"0","bottom":"0"},
      "blockGap": "var:preset|spacing|30"
    },
    "border": {
      "radius": "8px",
      "width": "1px",
      "color": "var:preset|color|contrast",
      "style": "solid"
    },
    "color": {
      "background": "#1a1a2e",
      "text": "#ffffff",
      "gradient": "linear-gradient(135deg,rgb(6,147,227) 0%,rgb(155,81,224) 100%)"
    },
    "typography": {
      "fontSize": "clamp(1rem, 2vw, 1.5rem)",
      "lineHeight": "1.4",
      "letterSpacing": "-0.02em"
    }
  }
}

Preset reference syntax in style values: var:preset|{type}|{slug} (not CSS var())

Preset Class Naming Convention

When using preset slugs (not inline style), blocks get CSS classes:

"backgroundColor":"primary" → has-primary-background-color has-background
"textColor":"contrast" → has-contrast-color has-text-color
"fontSize":"large" → has-large-font-size
"fontFamily":"heading" → has-heading-font-family
"gradient":"vivid-cyan-blue-to-vivid-purple" → has-vivid-cyan-blue-to-vivid-purple-gradient-background has-background

Block Locking

Prevent users from modifying pattern structure:

{
  "lock": {"move": true, "remove": true}
}

On container blocks, templateLock constrains children:

"templateLock":"all" — no insert, move, or remove
"templateLock":"insert" — no adding/removing, can move
"templateLock":"contentOnly" — only text/media editable, structure locked

Block Alignment

Use align attribute for wide/full-width:

{"align":"wide"}   <!-- respects wideSize -->
{"align":"full"}   <!-- breaks out to viewport edge -->

On this page