Installation

Ready to start building Gutenberg blocks at light speed? Here's how to get started with HTML To Gutenberg, whether you're spinning up a new project or integrating it into a custom Webpack setup.

Basic – Using @wordpress/create-block (Recommended)

The fastest and most foolproof way to get started.

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.

Advanced – Manually adding HTML To Gutenberg to an existing webpack configuration

If you’re using Webpack to build your custom blocks, you can easily integrate HTML To Gutenberg into your build process to automatically generate block.json, edit.js, render.php and index.js from simple HTML files.

Installation

npm install @jverneaut/html-to-gutenberg --save-dev

Webpack configuration

Add the plugin to your existing Webpack configuration:

webpack.config.js

import HTMLToGutenbergPlugin from "@jverneaut/html-to-gutenberg";

export default {
  plugins: [
    new HTMLToGutenbergPlugin({
      inputDirectory: "./blocks",
      outputDirectory: "./generated-blocks",
    }),
  ],
};

Plugin options

Option	Type	Default	Description
inputDirectory	string	None	Source folder for your custom blocks HTML files.
outputDirectory?	string	inputDirectory	Output folder that will contain the generated blocks files.
blocksPrefix?	string	'custom'	Prefix used for block names (e.g., custom/hero).
removeDeletedBlocks?	boolean	false	Whether to delete generated blocks if their source HTML files are removed.

warning

This page walks you through how to configure it manually — but keep in mind that HTML To Gutenberg is only responsible for generating the block files, not for compiling or bundling them. If you are an advanced webpack user and already have a webpack config that can compile blocks, then adding HTML To Gutenberg can be as simple as adding the plugin to your configuration and poiting to its outputdirectory in your custom configuration. For every other use case, I highly recommend using the standard @wordpress/create-block approach.

If you still want to delve into building blocks manually, you should use well-supported tools like @wordpress/scripts.

Bundling blocks with @jvenreaut/gutenberg-webpack-plugin

To make integrating @wordpress/scripts easier into an existing webpack configuration, I created @jverneaut/gutenberg-webpack-plugin. It’s heavily based on @wordpress/scripts and, while not 100% feature-complete, it makes bundling blocks much easier when using a custom Webpack setup.

It allows bundling blocks from inside your theme as opposed to a separate plugin, adding custom preprocessors using webpack, using TailwindCSS, etc.

Example config

webpack.config.js

import HTMLToGutenbergPlugin from "@jverneaut/html-to-gutenberg";
import GutenbergWebpackPlugin from "@jverneaut/gutenberg-webpack-plugin";

export default {
  mode: "development",
  entry: "./index.js", // Your main entry point for non-Gutenberg scripts

  plugins: [
    new HTMLToGutenbergPlugin({
      inputDirectory: "./blocks", // Source folder for your custom blocks HTML
      outputDirectory: "./generated-blocks", // Where transformed blocks will be output
    }),

    new GutenbergWebpackPlugin("./generated-blocks"), // Registers the generated blocks
  ],
};

info

When bundling blocks this way, don't forget to register them from the built output to make them available to WordPress. To learn how, head over to the next page.