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 18.12+ · GPL-2.0 · 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 real attachment ids. Plain core blocks anyone can edit in any WordPress, from whatever your model or design tool emits.
❯ block-runner convert hero.html
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
→ near-miss; run `block-runner fix` to canonicalize
exit 1 · gate failed (1 file)
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, correct nesting, real attachment ids.
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.
