A CLI to turn generated HTML into valid WordPress blocks.
Block Runner is the validity layer for WordPress blocks. Convert AI, agent, and design-tool output into nested native blocks, or validate the blocks you already have. Every result is proven against headless Gutenberg.
Works in GitHub Actions, GitLab CI, CircleCI, pre-commit, and the CLI. Any model, any vendor.
requires Node 20+ · GPL-2.0-or-later · Updated July 2026
<section class="hero relative" style="background-color:#0f172a">
<img src="hero.jpg" class="absolute inset-0 object-cover" />
<div class="absolute inset-0" style="background-color:rgba(15,23,42,0.5)"></div>
<div class="mx-auto max-w-3xl px-6 py-32 text-center">
<p style="color:#94a3b8">Native WordPress</p>
<h1 style="color:#ffffff">Design that editors can change.</h1>
<p style="color:#cbd5e1">No frozen Custom HTML. Real Cover, Group, Heading, and Button blocks—valid in the editor.</p>
<div class="mt-8 flex justify-center gap-3">
<a href="#" style="background-color:#f97316;color:#ffffff">Learn more</a>
<a href="#" style="color:#ffffff;border:1px solid rgba(255,255,255,0.2)">Contact us</a>
</div>
</div>
</section>
native blocks · editor-valid · theme adapted
- Coverhero.jpgdimRatio50overlayColorcontrast
- Group
- ParagraphNative WordPress
- Design that editors can change.textColorbase
- ParagraphNo frozen Custom HTML. Real Cover, Group, Heading, and Button blocks—valid in the editor.
- Buttons
- ButtonLearn morebackgroundColorprimarytextColorbase
- ButtonContact ustextColorbase
Block Runner is, in my opinion, the future of working with WordPress and AI.
Until now, I've struggled to find an easy way to convert AI "outputs" into useable WordPress elements, blocks, and landing pages.
But with Block Runner, I just share the HTML (+CSS) that Claude provides and converts it into useable WordPress assets.
I use Block Runner to build blocks from static HTML and was blown away by the speed and accuracy.
Being able to build functionality straight from core blocks instead of creating custom ones makes life so much easier, especially when managing larger projects.
I use Block Runner together with Claude CoWork for my WordPress site.
It allows me to create and customize theme blocks with KadenceWP very easily. The tool works reliably and removes a lot of friction from my development process.
For my workflow, it is a real time-saver.
Quick start
Copy this into Claude Code, Cursor, or any agentic editor to get started.
I've just globally installed npm package block-runner, which helps convert html to WordPress blocks (fetch the README: https://github.com/humanmade/block-runner/blob/main/README.md ). I then want you to convert hero.html (single block) and page.html (multiple blocks) and add these blocks to my WordPress site using WP CLI
my-wordpress-site on page/campaign | context: 94%
Two ways to use it.
Generate new blocks, or check the blocks you already have. The same validity check runs either way.
Converter
Convert generated HTML into native blocks
Real wp:cover > wp:columns > wp:buttons, properly nested, with the CSS mapped onto native block styling. Plain core blocks anyone can edit in any WordPress, from whatever your model or design tool emits.
❯ block-runner convert hero.html --resolver wpcli
reading hero.html … 1 section, 14 nodes
resolving media … 2 images → attachment ids
<!-- wp:cover {"dimRatio":50} -->
<!-- wp:columns -->
<!-- wp:column --> … <!-- /wp:column -->
<!-- /wp:columns -->
<!-- wp:buttons --> … <!-- /wp:buttons -->
<!-- /wp:cover -->
✓ editor-valid · 0 invalid blocks
Validator
Prove it is editor-valid
Every result is checked against headless Gutenberg itself, no LLM in the loop, so valid means what the editor means, not what a generator hoped. Deterministic, safe to run on every request and in CI.
❯ block-runner validate "content/**/*.html" --json
scanning 24 files against headless Gutenberg …
✓ 23 files valid
✗ landing.html:12 wp:columns may only contain wp:column
→ structural: wrap the child in wp:column to resolve
exit 1 · gate failed (1 file)
The CSS comes with it.
Since 0.6.0, Block Runner reads the CSS the generator wrote, both inline style attributes and single-class rules, and maps it onto native block styling. Padding lands in the spacing control, colours in the colour picker, type in the typography panel, all editable in Gutenberg rather than frozen in a Custom HTML blob.
Every declaration is accounted for: mapped onto a block attribute, consumed as block media, or reported with its line and selector. Nothing is dropped in silence.
<section class="card" style="background-color:#0f172a">
<h2>Ship it</h2>
<p>Every declaration accounted for.</p>
</section>
<style>
.card { padding: 32px; font-size: 18px; max-width: 600px }
</style>
❯ block-runner convert card.html --explain
background-color: #0f172a in [style] → style.color.background
padding: 32px in .card → style.spacing.padding
font-size: 18px in .card → style.typography.fontSize
⚠ max-width: 600px in .card dropped — no block attribute holds it
✓ editor-valid · 0 invalid blocks
Why we built it.
The agentic ecosystem moves fast. Models, agents, and design tools can produce WordPress content quicker than ever, but the HTML they emit converts to blocks weakly, inconsistently, or not at all, and nothing checks whether the result is valid.
We built it because we needed it ourselves, to run autonomous optimisation experiments on Accelerate, then open-sourced it as the primitive the ecosystem was missing, so every tool in the pipeline can trust the blocks it ships.
The chart scores how close each result lands to a known-ideal block tree, validated against headless Gutenberg, the same parser the editor runs. Higher means blocks the editor accepts as-is: matching save() output and correct nesting.
block-runner
Common questions
Built by WordPress Experts
Created by Human Made
Since 2010, Human Made has been one of the world's leading enterprise WordPress agencies, powering platforms for Google, TechCrunch, Harvard, and Siemens. Accelerate brings that same level of expertise to your WordPress site.
