Forem: Julien Verneaut

Introducing HTML to Gutenberg: Turn HTML Files into editable Gutenberg Blocks

Julien Verneaut — Mon, 07 Apr 2025 08:02:24 +0000

TLDR: I created a CLI and webpack plugin that converts HTML files into fully featured, dynamic Gutenberg Blocks. It allows developers to write custom blocks up to 5x faster.

You can find it here: HTML To Gutenberg.

There Has To Be a Better Way to Develop Custom Gutenberg Blocks

I love Gutenberg. So do my clients.

But like many fellow WordPress developers raised on ACF and the good old way™ of building websites, I was hesitant at first to fully embrace Gutenberg.

I mean—have you tried building a full site using only custom Gutenberg Blocks?

For every block, here’s what the process typically looks like:

Draft out the HTML and style it until everything looks just right.
Scaffold a new block using either wp scaffold block for static blocks, or the excellent @wordpress/create-block tool for dynamic ones.
Paste your HTML into the render.php file.
Paste it again into the edit.js (React) file.
"Reactify" the markup by converting class= to className=, fixing self-closing tags, and transforming attributes to their React equivalents.
Define attributes in block.json.
Add React components to allow editing those attributes in the editor (<RichText />, <MediaUpload />, etc.).
Pass those attribute values to render.php and map them to your HTML.

Now, this isn’t exactly rocket science—but it is tedious, repetitive, and error-prone. Every time I find myself repeating code or patterns for the tenth time, my developer 6th sense kicks in and starts whispering:

There has to be a better way...

How to Develop Dynamic Gutenberg Blocks from a Single HTML File

So... I built one.

Introducing HTML to Gutenberg: a CLI and webpack plugin that converts valid HTML files into fully functional, dynamic Gutenberg blocks—powered by React in the editor and rendered in either PHP or Twig on the frontend.

In other words: write once, and get the whole block. No more copy-pasting. No more Reactifying. No boilerplate.

Just fast, efficient block development.

Let's look an an example:

HTML Input

<section class="container">
  <h1 data-attribute="title">Hello, <strong>Dev.to!</strong></h1>
  <img data-attribute="image">
</section>

Generated edit.js

import { useBlockProps, RichText, MediaUpload } from "@wordpress/block-editor";
import { Image } from "@10up/block-components";

export default ({ attributes, setAttributes }) => {
  return (
    <section {...useBlockProps({ className: "container" })}>
      <RichText
        tagName="h1"
        value={attributes.title}
        onChange={(title) => setAttributes({ title })}
      ></RichText>
      <MediaUpload
        value={attributes.image}
        onSelect={(image) => setAttributes({ image: image.id })}
        render={({ open }) => (
          <Image
            style={{ cursor: "pointer" }}
            onClick={open}
            id={attributes.image}
            onSelect={(image) => setAttributes({ image: image.id })}
          />
        )}
      ></MediaUpload>
    </section>
  );
};

Generated render.php

<?php

$image = wp_get_attachment_image_src($attributes['image'], 'full');
$image_alt = get_post_meta($attributes['image'], '_wp_attachment_image_alt', true);
?>

<section <?php echo get_block_wrapper_attributes(['class' => 'container']); ?>>
  <h1><?php echo wp_kses_post($attributes['title'] ?? ''); ?></h1>
  <img src="<?php echo esc_url($image[0]); ?>" alt="<?php echo esc_attr($image_alt); ?>" />
</section>

Generated block.json

{
  "name": "custom/team",
  "title": "Team",
  "textdomain": "team",
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "version": "0.1.0",
  "category": "theme",
  "example": {},
  "attributes": {
    "align": { "type": "string", "default": "full" },
    "title": { "type": "string", "default": "Hello, <strong>Dev.to!</strong>" },
    "image": { "type": "integer" }
  },
  "supports": { "html": false, "align": ["full"] },
  "editorScript": "file:./index.js",
  "render": "file:./render.php"
}

How It Works

You write a single HTML file that represents your block’s output.
You add a few simple annotations in your HTML to define dynamic fields (e.g. data-attribute="title").
You run the CLI or use the Webpack plugin in your theme or plugin build process.
It generates:
- The block.json file
- A fully working edit.js file using proper React components (like RichText, MediaUpload, etc.)
- A frontend render file (either PHP or Twig—your choice)
- The required index.js file to register the block with WordPress

And just like that, your HTML is now a dynamic Gutenberg block, ready to use and edit in the WordPress Block Editor ✨.

It currently supports text and image attributes, as well as defining InnerBlocks areas and templates using custom <blocks> and <block name="custom/child-block"> elements.

You can find more information and documentation on HTML To Gutenberg Documentation site.

Why This Is a Game Changer for WordPress Developers and Agencies

I genuinely believe that when done right, Gutenberg offers one of the best content editing experiences available on any CMS — even when compared to modern visual builders like Framer or Webflow.

It strikes a pretty good balance between giving clients flexibility while letting developers maintain design and code consistency at scale.

But the development process? It's tedious. It leads to duplicated code. And while tools like ACF Blocks exist, they still don’t offer the seamless "click and edit" experience of native Gutenberg blocks.

With HTML to Gutenberg, you can now:

Develop native blocks up to 5x faster
Eliminate unnecessary duplication
Focus more on design and functionality, not setup
Version, share, and maintain your blocks easily

This unlocks new workflows for teams and agencies, especially those looking to industrialize their processes:

Turn Tailwind UI components into editable Gutenberg blocks in minutes Grab a Tailwind UI snippet, add a few annotations, and boom — it's a fully editable block.
Build internal libraries of reusable blocks Your agency can now standardize, document, and reuse high-quality blocks across projects with zero friction.
Copy-paste blocks across sites With everything contained in one HTML file, portability has never been easier.

Try It Out

You can check it out here: HTML To Gutenberg

Whether you're working on a client project, building a theme, or contributing to a design system of reusable blocks, this tool is here to make your Gutenberg life easier.

Let me know what you think—I'd love feedback from the community. And if you end up using this in your projects, let me know how it goes!

Which country has the most content on Wikipedia?

Julien Verneaut — Thu, 29 Aug 2024 09:01:00 +0000

Introduction

When I search for something on the internet, I often find that English content is much more comprehensive than French content.

Although it might seem obvious given the number of English speakers in the world compared to French speakers (about 4 to 5 times more), I wanted to test this hypothesis and quantify it.

TLDR: On average, an English article on Wikipedia contains 19% more information than its French counterpart.

The source code for this analysis is available here: https://github.com/jverneaut/wikipedia-analysis/

Protocole

Wikipedia is one of the largest sources of quality content on the web worldwide.

At the time of writing this article, the English version has over 6,700,000 unique articles compared to only 2,500,000 for the French version. We will use this corpus as the basis for our study.

Using the Monte Carlo method, we will sample random articles from Wikipedia for each language and calculate the average character length of this corpus. With a sufficiently large number of samples, we should obtain results close to reality.

Since the Wikimedia API does not provide a method to get the character length of an article, we will obtain this information as follows:

Retrieve the byte size of a large sample of articles via the Wikimedia API.
Estimate the number of bytes per character from a small sample of articles using the Monte Carlo method.
Retrieve the character count of a large number of articles using the byte-per-character estimate obtained in step 2.

As we are using the Monte Carlo method to estimate bytes per character, we need the largest possible number of articles to minimize deviation from the actual number.

The Wikimedia API documentation specifies these limitations:

No more than 500 random articles per request.
No more than 50 article contents per request.

Taking these limitations into account and as a compromise between precision and query execution time, I chose to sample 100,000 articles per language as a reference for article byte length and 500 articles to estimate the bytes per character for each language.

Limitations

Currently, the Wikimedia API returns its own wikitext format when asked to provide the content of an article. This format is not plain text and is closer to HTML. Since all languages on Wikimedia use this same format, I estimated that we could rely on it without influencing the direction of our final results.

However, some languages are more verbose than others. For example, in French, we say "Comment ça va?" (15 characters) compared to "How are you?" (12 characters) in English. This study does not account for this phenomenon. If we wanted to address it, we could compare different translations of the same book corpus to establish a "density" correction variable for languages. In my research, I did not find any data that provides a ratio to apply to each language.

However, I did find a very interesting paper that compares the information density of 17 different languages and the speed at which they are spoken. Its conclusion is that the most "efficient" languages are spoken more slowly than the least efficient ones, resulting in a verbal information transmission rate consistently around ~39 bits per second.

Interesting.

Get the average byte length of articles in each language

As stated in the protocol, we will use a Wikipedia API to retrieve 500 random articles in a given language.

def getRandomArticlesUrl(locale):
    return "https://" + locale + ".wikipedia.org/w/api.php?action=query&generator=random&grnlimit=500&grnnamespace=0&prop=info&format=json"

def getRandomArticles(locale):
    url = getRandomArticlesUrl(locale)
    response = requests.get(url)
    return json.loads(response.content)["query"]["pages"]

This then gives us a response like { "id1": { "title": "...", "length": 1234 }, "id2": { "title": "...", "length": 5678 }, ... } which we can use to retrieve the size in bytes of a large number of articles.

This data is then reworked to obtain the following table:

Language	Average length	...
EN	8865.33259
FR	7566.10867
RU	10923.87673
JA	9865.59485
...

At first glance, it would seem that articles in English have a larger byte length than those in French. Similarly, those in Russian have a larger byte length than those in any other language.

Should we stop at this conclusion? Not quite. Since the length reported by Wikipedia is a length in bytes, we need to delve a little deeper into how characters are encoded to understand these initial results.

How Letters Are Encoded: An Introduction to UTF-8

What is a byte?

Unlike you and me, a computer has no concept of letters, let alone an alphabet. For it, everything is represented as a sequence of 0s and 1s.

In our decimal system, we go from 0 to 1, then from 1 to 2, and so on, up to 10.

For the computer, which uses a binary system, we go from 0 to 1, then from 1 to 10, then from 10 to 11, 100, and so forth.

Here is a comparison table to make it clearer:

Decimal	Binary
0	0
1	1
2	10
3	11
4	100
5	101
6	110
7	111
8	1000
9	1001
10	1010
...

Learning binary goes well beyond the scope of this article, but you can see that as the number becomes larger, its binary representation is "wider" compared to its decimal representation.

Since a computer needs to distinguish between numbers, it stores them in small packets of 8 units called bytes. A byte is composed of 8 bits, for example, 01001011.

How UTF-8 stores characters

We have seen how to store numbers, it gets a little more complicated for storing letters.

Our Latin alphabet used in many Western countries uses an alphabet of 26 letters. Couldn't we just use a reference table where each number from 0 to 25 corresponds to a letter?

Letter	Index	Binary index
a	0	00000000
b	1	00000001
c	2	00000010
...	...	...
z	25	00011001

But we have more characters than just lowercase letters. In this simple sentence, we also have uppercase letters, commas, periods, etc. A standardized list was created to include all these characters within a single byte, known as the ASCII standard.

At the dawn of computing, ASCII was sufficient for basic uses. But what if we want to use other characters? How do we write with the Cyrillic alphabet (33 letters)? This is why the UTF-8 standard was created.

UTF-8 stands for Unicode (Universal Coded Character Set) Transformation Format - 8 bits. It is an encoding system that allows a computer to store characters using one or more bytes.

To indicate how many bytes are used for the data, the first bits of this encoding are used to signal this information.

First UTF-8 bits	Number of bytes used
0xxxxxx	1
110xxxxx ...	2
1110xxxx ... ...	3
11110xxx ... ... ...	4

The following bits also have their purpose, but once again, this goes beyond the scope of this article. Just note that, at a minimum, a single bit can be used as a signature in cases where our character fits within the x1111111 = 127 remaining possibilities.

For English, which does not use accents, we can assume that most characters in an article will be encoded this way, and therefore the average number of bytes per character should be close to 1.

For French, which uses accents, cedillas, etc., we assume that this number will be higher.

Finally, for languages with a more extensive alphabet, such as Russian and Japanese, we can expect a higher number of bytes, which provides a starting point for explaining the results obtained earlier.

Get the average character length in bytes of articles for each language

Now that we understand what the value returned earlier by the Wikipedia API means, we want to calculate the number of bytes per character for each language in order to adjust these results.

To do this, we use a different way of accessing the Wikipedia API that allows us to obtain both the content of the articles and their byte length.

Why not use this API directly?

This API only returns 50 results per request, whereas the previous one returns 500. Therefore, in the same amount of time, we can get 10 times more results this way.

More concretely, if the API calls took 20 minutes with the first method, they would take 3 hours and 20 minutes with this approach.

def getRandomArticlesUrl(locale):
    return "https://" + locale + ".wikipedia.org/w/api.php?action=query&generator=random&grnlimit=50&grnnamespace=0&prop=revisions&rvprop=content|size&format=json"

def getRandomArticles(locale):
    url = getRandomArticlesUrl(locale)
    response = requests.get(url)
    return json.loads(response.content)["query"]["pages"]

Once this data is synthesized, here is an excerpt of what we get:

Language	Bytes per character	...
EN	1.006978892420735
FR	1.0243214042939228
RU	1.5362439940531318
JA	1.843857157700553
...

So our intuition was correct: countries with a larger alphabet distort the data because of the way their content is stored.

We also see that French uses more bytes on average to store its characters than English as we previously assumed.

Results

We can now correct the data by changing from a size in bytes to a size in characters which gives us the following graph:

Our hypothesis is therefore confirmed.

On average, English is the language with the most content per page on Wikipedia. It is followed by French, then Russian, Spanish, and German.

The standard deviation (shown with the black bars) is large for this dataset, which means that the content size varies greatly from the shortest to the longest article. Therefore, it is difficult to establish a general truth for all articles, but this trend still seems consistent with my personal experience of Wikipedia.

If you want all the results from this experiment, I have also created this representation, which compares each language with its percentage of additional/less content relative to the others.

Thanks to this, we therefore find our conclusion that on average, an English article on Wikipedia contains 19% more information than its equivalent in French.

The source code for this analysis is available here: https://github.com/jverneaut/wikipedia-analysis/

Writing a state management library in 50 lines of JavaScript

Julien Verneaut — Fri, 23 Aug 2024 19:44:32 +0000

State management is one of the most important part of a web application. From the use of global variables to React hooks to the use of third-party libraries like MobX, Redux or XState to name just these 3, it is one of the topics that fuels the most discussions as it is important to master it to design a reliable and efficient application.

Today, I propose to build a mini state management library in less than 50 lines of JavaScript based on the concept of observables. This one can certainly be used as-is for small projects, but beyond this educational exercise I still recommend you to turn to more standardized solutions for your real projects.

API Definition

When starting a new library project, it is important to define what its API could look like from the beginning in order to freeze its concept and guide its development before even thinking about technical implementation details. For a real project, it is even possible to begin writing tests at this time to validate the implementation of the library as it is written according to a TDD approach.

Here we want to export a single class that we will call State that will be instantiated with an object containing the initial state and a single observe method that allows us to subscribe to state changes with observers. These observers should only be executed if one of their dependencies has changed.

To change the state, we want to use the class properties directly rather than going through a method like setState.

Because a code snippet is worth a thousand words, here's what our final implementation might look like in use:

const state = new State({
  count: 0,
  text: '',
});

state.observe(({ count }) => {
  console.log('Count changed', count);
});

state.observe(({ text }) => {
  console.log('Text changed', text);
});

state.count += 1;
state.text = 'Hello, world!';
state.count += 1;

// Output:
// Count changed 1
// Text changed Hello, world!
// Count changed 2

Implementing the State class

Let's start by creating a State class that accepts an initial state in its constructor and exposes an observe method that we will implement later.

class State {
  constructor(initialState = {}) {
    this.state = initialState;
    this.observers = [];
  }

  observe(observer) {
    this.observers.push(observer);
  }
}

Here we choose to use an internal intermediate state object that will allow us to keep the state values. We also store the observers in an internal observers array that will be useful when we complete this implementation.

Since these 2 properties will only be used inside this class, we could declare them as private with a little syntactic sugar by prefixing them with a # and adding an initial declaration on the class:

class State {
  #state = {};
  #observers = [];

  constructor(initialState = {}) {
    this.#state = initialState;
    this.#observers = [];
  }

  observe(observer) {
    this.#observers.push(observer);
  }
}

In principle this would be a good practice, but we will use Proxies in the next step and they are not compatible with private properties. Without going into detail and to make this implementation easier, we will use public properties for now.

Read data from the state object with a Proxy

When we outline the specifications for this project, we wanted to access the state values directly on the class instance and not as an entry to its internal state object.

For this, we will use a proxy object which will be returned when the class is initialized.

As its name suggests, a Proxy allows you to create an intermediary for an object to intercept certain operations, including its getters and setters. In our case, we create a Proxy exposing a first getter that allows us to expose the state object's inputs as if they belonged directly to the State instance.

class State {
  constructor(initialState = {}) {
    this.state = initialState;
    this.observers = [];

    return new Proxy(this, {
      get: (target, prop) => {
        if (prop in target.state) {
          return target.state[prop];
        }

        return target[prop];
      },
    });
  }

  observe(observer) {
    this.observers.push(observer);
  }
}

const state = new State({
  count: 0,
  text: '',
});

console.log(state.count); // 0

Now we can define an initial state object when instantiating State and then retrieve its values directly from that instance. Now let's see how to manipulate its data.

Adding a setter to modify the state values

We added a getter, so the next logical step is to add a setter allowing us to manipulate the state object.

We first check that the key belongs to this object, then check that the value has indeed changed to prevent unnecessary updates, and finally update the object with the new value.

class State {
  constructor(initialState = {}) {
    this.state = initialState;
    this.observers = [];

    return new Proxy(this, {
      get: (target, prop) => {
        if (prop in target.state) {
          return target.state[prop];
        }

        return target[prop];
      },
      set: (target, prop, value) => {
        if (prop in target.state) {
          if (target.state[prop] !== value) {
            target.state[prop] = value;
          }
        } else {
          target[prop] = value;
        }
      },
    });
  }

  observe(observer) {
    this.observers.push(observer);
  }
}

const state = new State({
  count: 0,
  text: '',
});

console.log(state.count); // 0
state.count += 1;
console.log(state.count); // 1

We are now done with the data reading and writing part. We can change the state value and then retrieve that change. So far our implementation is not very useful, so let's implement observers now.

Implementing Observers

We already have an array containing the observers functions declared on our instance, so all we have to do is call them one by one whenever a value has changed.

class State {
  constructor(initialState = {}) {
    this.state = initialState;
    this.observers = [];

    return new Proxy(this, {
      get: (target, prop) => {
        if (prop in target.state) {
          return target.state[prop];
        }

        return target[prop];
      },
      set: (target, prop, value) => {
        if (prop in target.state) {
          if (target.state[prop] !== value) {
            target.state[prop] = value;

            this.observers.forEach((observer) => {
              observer(this.state);
            });
          }
        } else {
          target[prop] = value;
        }
      },
    });
  }

  observe(observer) {
    this.observers.push(observer);
  }
}

const state = new State({
  count: 0,
  text: '',
});

state.observe(({ count }) => {
  console.log('Count changed', count);
});

state.observe(({ text }) => {
  console.log('Text changed', text);
});

state.count += 1;
state.text = 'Hello, world!';

// Output:
// Count changed 1
// Text changed 
// Count changed 1
// Text changed Hello, world!

Great, we are now reacting to data changes!

Small problem though. If you've been paying attention this far, we originally wanted to run the observers only if one of their dependencies changed. However, if we run this code we see that each observer runs every time a part of the state is changed.

But then how can we identify the dependencies of these functions?

Identifying Function Dependencies with Proxies

Once again, Proxies come to our rescue. To identify the dependencies of our observer functions, we can create a proxy of our state object, run them with it as an argument, and note which properties they accessed.

Simple, but effective.

When calling observers, all we have to do is check if they have a dependency on the updated property and trigger them only if so.

Here is the final implementation of our mini-library with this last part added. You will notice that the observers array now contains objects allowing to keep the dependencies of each observer.

class State {
  constructor(initialState = {}) {
    this.state = initialState;
    this.observers = [];

    return new Proxy(this, {
      get: (target, prop) => {
        if (prop in target.state) {
          return target.state[prop];
        }

        return target[prop];
      },
      set: (target, prop, value) => {
        if (prop in target.state) {
          if (target.state[prop] !== value) {
            target.state[prop] = value;

            this.observers.forEach(({ observer, dependencies }) => {
              if (dependencies.has(prop)) {
                observer(this.state);
              }
            });
          }
        } else {
          target[prop] = value;
        }
      },
    });
  }

  observe(observer) {
    const dependencies = new Set();

    const proxy = new Proxy(this.state, {
      get: (target, prop) => {
        dependencies.add(prop);
        return target[prop];
      },
    });

    observer(proxy);
    this.observers.push({ observer, dependencies });
  }
}

const state = new State({
  count: 0,
  text: '',
});

state.observe(({ count }) => {
  console.log('Count changed', count);
});

state.observe(({ text }) => {
  console.log('Text changed', text);
});

state.observe((state) => {
  console.log('Count or text changed', state.count, state.text);
});

state.count += 1;
state.text = 'Hello, world!';
state.count += 1;

// Output:
// Count changed 0
// Text changed 
// Count or text changed 0 
// Count changed 1
// Count or text changed 1 
// Text changed Hello, world!
// Count or text changed 1 Hello, world!
// Count changed 2
// Count or text changed 2 Hello, world!

And there you have it, in 45 lines of code we have implemented a mini state management library in JavaScript.

Going further

If we wanted to go further, we could add type suggestions with JSDoc or rewrite this one in TypeScript to get suggestions on properties of the state instance.

We could also add an unobserve method that would be exposed on an object returned by State.observe.

It might also be useful to abstract the setter behavior into a setState method that allows us to modify multiple properties at once. Currently, we have to modify each property of our state one by one, which may trigger multiple observers if some of them share dependencies.

In any case, I hope that you enjoyed this little exercise as much as I did and that it allowed you to delve a little deeper into the concept of Proxy in JavaScript.