Skip to main content

HTML To Gutenberg - Convert HTML to Gutenberg blocks

HTML to Gutenberg is a Webpack plugin that compiles your HTML into real, native Gutenberg blocks. No shortcodes. No server-side hacks. The real Gutenberg editing experience.

It generates proper edit.js, render.php, block.json, and index.js files, exactly what you'd write by hand if you were building blocks with React and PHP.

But you won’t have to write a single line of React or PHP.

Just structure your HTML with a few intuitive attributes, and let the plugin handle the heavy lifting.

The output is 100% native Gutenberg code. If you stop using the plugin, your blocks still work. No lock-in.

Try it out in the Live Editor to see how quickly you can convert your HTML into Gutenberg blocks.

HTML To Gutenberg WordCamp Demo

Why HTML To Gutenberg?​

If you’ve built Gutenberg blocks the traditional way, you’ve probably asked yourself:

  • Why am I duplicating layout in both React and PHP?
  • Why does a simple block need 4 different files?
  • Why can’t I just write HTML and be done?

Now you can. HTML To Gutenberg gives you a radically simpler way to build blocks — while still compiling down to 100% standard Gutenberg code under the hood.

It works great whether you're a developer in quest of a better blocks developer experience, an agency building custom themes, or a product team maintaining a block library.

Try it live​

Type some HTML. Add attributes. Add InnerBlocks. Done. 🎉

Open the live code editor

Edit this code to see the generated Gutenberg block files.

block.html
<section
  class="py-20 bg-blue-200"
  data-parent="custom/parent-block"
  data-editing-mode="contentOnly"
>
  <inspector-controls>
    <panel-body title="Settings">
      <select-control data-bind="postType" label="Post Type">
        <select-control-option value="posts">Posts</select-control-option>
        <select-control-option value="pages">Pages</select-control-option>
      </select-control>
    </panel-body>
  </inspector-controls>

  <div class="container">
    <div class="grid grid-cols-12 gap-4">
      <div class="col-span-12 md:col-span-6">
        <h2 class="text-2xl" data-bind="sectionTitle">
          Edit me inside the editor
        </h2>
        <img class="aspect-square object-cover" data-bind="sectionImage" />
      </div>

      <div class="col-span-12 md:col-span-6">
        <inner-blocks allowedBlocks="all" templateLock="all">
          <inner-block name="core/group">
            <inner-block name="core/heading" level="3"></inner-block>
            <inner-block name="core/paragraph">
              <block-attribute name="content">
                Lorem ipsum dolor sit amet consectetur.
              </block-attribute>
            </inner-block>
          </inner-block>
        </inner-blocks>
      </div>
    </div>

  </div>
</section>

Quick start​

This project is built with ESM and requires Node.js version 20.0.0 or later.

1. Scaffold an HTML To Gutenberg blocks plugin​

cd wp-content/plugins
npx @wordpress/create-block --template html-to-gutenberg-template

This sets up everything you need — pre-configured to work with HTML To Gutenberg.

2. Start development​

cd html-to-gutenberg-blocks # Your block plugin directory
npm run start

3. Edit the default block​

Open wp-content/plugins/html-to-gutenberg-blocks/src/block.html and make changes to the default block.

HTML To Gutenberg will automatically convert it into a working Gutenberg block.

4. Add additional blocks​

To create additional blocks, simply add new .html files in the src folder.

Each HTML file becomes its own block and is automatically processed by HTML To Gutenberg.

src/
├── block.html         # Default block (can be safely deleted)
├── hero.html          # Another custom block
├── testimonial.html   # Yet another one
Note about blocks deletion

When you delete an HTML file from src, its corresponding Gutenberg block is removed on the next build.

However, depending on your setup, you may also need to manually delete the removed block folder inside the build/ directory to fully clean it up.

5. Activate your plugin​

Enable your block in the WordPress admin and drop it into any page or post.

Can't see your plugin on the admin?
warning

Make sure you set a title when generating the plugin with @wordpress/create-block. If you don’t, the plugin may not appear in the WordPress plugins page.

If you forgot to add one, open the root PHP file of your plugin and add a Plugin Name like so:

<?php

/**
 * Plugin Name:       HTML To Gutenberg Blocks <------ Add a name here
 * Version:           0.1.0
 * Requires at least: 6.7
 * Requires PHP:      7.4
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       textdomain
 *
 * @package CreateBlock
 */

6. Build for production​

npm run build

Bundles and minifies your blocks.

Supported features​

FeatureSupported
Inline editable fields✅
InnerBlocks with templates✅
Server-side rendering (PHP)✅
Editor rendering (JSX)✅
Block styles✅
Block editing mode✅
Block parent blocks✅
block.json metadata✅
InspectorControls✅

How it works​

HTML To Gutenberg uses an Abstract Syntax Tree (AST) to parse your HTML block files, preserving your original markup structure. It interprets custom attributes and transforms this tree into all the necessary Gutenberg block assets — including metadata, editor components, frontend renderers, and block registration files.

Built for modern WordPress teams​

Give your clients a truly intuitive and seamless editing experience with HTML To Gutenberg. Designed to unlock the full potential of Gutenberg, it empowers you to create rich, dynamic blocks faster — all while maintaining clean, maintainable code.

Push the boundaries of what’s possible in the block editor and deliver custom solutions that delight editors and developers alike.

Real blocks. Real fast.