WordPress Rant #001

deep breath

So, WordPress is having a bit of an identity crisis with it's theming support.

There are two types of themes:

• Good old "classic themes". Written in PHP, and customized by the Customizer, which only supports options specifically declared by the theme.
• The new "block themes". These are written in pure HTML and comment markup. They are fully editable in the new WYSIWYG theme editor, and you can reuse blocks from the theme in your own pages, posts, etc.

Now, having two theming options is not a problem. The interop is actually pretty nice: you can render posts that use blocks from classic themes, and you can also expose your own blocks from classic themes, which can also use PHP. The issue mainly manifests in two parts: syntax design, and documentation.

The Problem

The block theme syntax seems fine at first glance. The introduction shows this snippet which prints the site's title as an <h1>:

<!-- wp:site-title /-->

This seems fine! However, that's because this is a self-contained block. When you actually want to make something with structure, you end up writing shit like this:

<!-- wp:group {"align":"full", "layout": {"type":"flex","allowOrientation":false,"justifyContent":"space-between"}, "className": "my-class"} -->
<div class="wp-block-group alignfull is-layout-flex is-content-justification-space-between my-class">
    <!-- wp:paragraph -->
    <p>This is on the left</p>
    <!-- /wp:paragraph -->

    <!-- wp:paragraph -->
    <p>This is on the right</p>
    <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

Now, this is disgusting for a lot of reasons.

1. You have to declare everything twice, in two different ways. Once in the comment, written in the comment declaration format, and once in HTML, using the built-in classes.
2. The comment declaration format is essentially undocumented. This reference page exists, but whoever called it a refrence should be fined for false advertisement. What the fuck does Supports: align, anchor, color (background, text)... even mean? What are possible values for align?
3. The built-in classes are named completely inexpicably. "layout": {"type": "flex"} needs the class is-layout-flex. So, by that logic, "align": "full" would need is-align-full, right? Nope! It needs alignfull!
4. The built-in classes are completely undocumented. It is by pure chance that I found alignfull while scouring through examples, and I only found the classes for flex stuff in a blog post.
5. "layout" is also COMPLETELY UNDOCUMENTED. I had to dig through WP source code to find even simple stuff like "flexWrap": "nowrap" (because wrap is the default, for some reason).
6. Apparently, the proper way to write block themes is by designing them in the WYSIWYG editor. How is that appropriate at all? Who thought that was a good idea? Did they forget about people working from Figma designs? WTF?!?!?!?!?
7. Even if you tried to use the WYSIWYG editor, you'd get a brain aneurysm in mere minutes. The editor is fine for text editing, but once you try to do layouting stuff, you'll lose your mind. It's such a terrible experience.
8. The worst part of it all: The editor will take the comment declarations you write, generate HTML from it, and match it against the HTML you wrote. If it doesn't match, it'll freak out and show a weird Block Recovery thing. IF YOU CAN GENERATE HTML FROM MY COMMENT DECLARATIONS, WHY DO YOU NEED ME TO ALSO WRITE IT AS HTML. WHAT.