Uncategorized

Gutenberg Times: Block Format Bridge: A Practical Solution for AI-Generated Content in WordPress

jaswantkaurm@gmail.com3 months ago1239 mins

Chris Huber, developer at Automattic, released Block Format Bridge, an open-source plugin that addresses one of the more persistent friction points in AI-assisted WordPress workflows: getting AI-generated content into the block editor reliably.

The plugin takes a pragmatic approach. Block markup is notoriously difficult for AI to produce correctly — not because AI models lack capability, but because of how the format works. As Dennis Snell explained back in 2017 in his still-essential post Gutenberg posts aren’t HTML, a Gutenberg post is a serialized tree structure that happens to be stored as HTML with JSON-carrying comment delimiters. It was never designed to be written by hand — or by an AI inferring its way through a save() function it can’t actually execute. The result, for anyone building publishing automations, REST API integrations, or agent workflows that call wp_insert_post(), is a familiar failure mode: content that saves fine, then opens in the editor with invalid blocks or silently falls back to the classic editor.

Even a block as common as a styled quote illustrates the problem:

The generated HTML should be treated as throwaway code.

Dennis Snell

JSON

<!-- wp:quote {"className":"is-style-large"} -->
<blockquote class="wp-block-quote is-style-large">
    <p>The generated HTML should be treated as throwaway code.</p>
    <cite>Dennis Snell</cite>
</blockquote>
<!-- /wp:quote -->

<!-- wp:quote {"className":"is-style-large"} -->
<blockquote class="wp-block-quote is-style-large">
    <p>The generated HTML should be treated as throwaway code.</p>
    <cite>Dennis Snell</cite>
</blockquote>
<!-- /wp:quote -->

The className attribute in the comment has to match the class on the HTML element. The cite tag must follow the exact structure the block’s save() function produces. Get either wrong and the block is invalid — and with more complex blocks like wp:cover or wp:columns, the surface area for errors grows considerably.

HTML to Blocks converter and vice versa

Block Format Bridge sidesteps the problem by letting AI output what it does well — Markdown or plain HTML — and handling the conversion to block markup server-side, using established PHP libraries. It builds on chubes4/html-to-blocks-converter for the write side, WordPress core’s do_blocks() for rendering, and league/commonmark and league/html-to-markdown for Markdown support.

The core API is compact and readable:

JSON

/ Markdown → blocks
$blocks = bfb_convert( "# HellonnSome content here.", 'markdown', 'blocks' );

/ HTML → blocks
$blocks = bfb_convert( '<h1>Hello</h1><p>Some content here.</p>', 'html', 'blocks' );

/ Blocks → Markdown (for reading back to AI)
$md = bfb_render_post( $post_id, 'markdown' );

/ Markdown → blocks
$blocks = bfb_convert( "# HellonnSome content here.", 'markdown', 'blocks' );

/ HTML → blocks
$blocks = bfb_convert( '<h1>Hello</h1><p>Some content here.</p>', 'html', 'blocks' );

/ Blocks → Markdown (for reading back to AI)
$md = bfb_render_post( $post_id, 'markdown' );

It also adds a ?content_format= query parameter to the REST API, so AI agents can fetch existing post content as Markdown — not raw block markup — which makes edit workflows considerably more reliable.

The architecture is extensible. New formats can be added by registering a new adapter without touching the core bridge, and the bfb_default_format filter lets you declare that a custom post type writes in Markdown by default, so any code path calling wp_insert_post() gets the same conversion behavior automatically.

Does This Need a Skill?

After sharing an early draft of this post with Chris Huber, he offered a perspective worth sitting with: this plugin is designed to eliminate a skill rather than add one.

When Block Format Bridge is bundled as a dependency and the system prompt simply instructs the agent to insert post content as Markdown, the AI doesn’t need to know the plugin exists at all. A single line — “post content should be inserted as Markdown” — is enough. The conversion happens automatically, invisibly, in PHP. The complexity disappears into infrastructure rather than into instructions.

That’s a different philosophy from agent-skills, which is about making AI aware of patterns and tools. The more elegant approach here is the opposite: good tooling that makes the AI less aware, not more. An end user of a plugin built on top of Block Format Bridge would never know it exists — they’d just see valid blocks in the editor.

A skill may still have a role for developers who don’t control the system prompt and need to guide agent behavior through other means. But for anyone building AI-powered WordPress plugins or automations, the cleaner pattern is to bundle the plugin, set the default format, and let the infrastructure do its job.

A draft skill is available below for those who do want to experiment with the agent-skills approach.

A draft skill can be downloaded to use the Block Format Bridge .

wp-block-content-skill Download

All is still a work in progress so there might be dragons

As a small footnote, this post was drafted with AI assistance and had to be converted to blocks before I could edit it. —which felt fitting given the subject