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
<section class="hero relative bg-slate-950">
<img src="porthole.jpg" class="absolute inset-0 object-cover" />
<div class="mx-auto max-w-3xl px-6 py-32 text-center">
<p class="text-xs uppercase tracking-widest">The first crewed crossing</p>
<h1 class="mt-4 text-5xl font-semibold">Past the last light of the sun.</h1>
<p class="mt-6 text-lg text-white/70">A crewed passage to Proxima Centauri b.</p>
<div class="mt-8 flex justify-center gap-3">
<a href="#" class="btn bg-orange-500 px-5 py-2.5">Reserve a berth</a>
<a href="#" class="btn ring-1 ring-white/20">See the trajectory</a>
</div>
</div>
</section>
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.
