Tag Archives: Gutenberg

The final (?) verdict: Gutenberg (a.k.a. the WordPress “Block Editor”) is fundamentally flawed and unsustainable

I’ve been trying. Really I have.

From its initial release as part of the WordPress core in version 5.0 in late 2018, up until early 2022, I adamantly refused to use Gutenberg. I felt its conceptual flaws and practical limitations were so profound and so obvious that I really could not believe this was going to be “the future of WordPress.” And now here we are.

In the spring of 2022 I finally relented, as at least the initial impression of the user interface had improved to a point where I felt I just needed to embrace it or move on. And so I created a new base “Block Theme” for future WordPress projects, and began building new client sites with it.

The past year and a half of dealing with Gutenberg more directly has been a painful rollercoaster of emotions, as I’ve tried repeated to convince myself it’s good, only to have it, once again, prove itself a hot mess of ill-conceived and barely-documented hacks.

Many times in the past 18 or so months I have contemplated abandoning WordPress for good, checking out ClassicPress and some other CMS options before falling back on giving Gutenberg another chance.

I’ve even considered writing my own Content Management System (CMS) [again; it’s something I specialized in before 2014]; switching to Drupal, for God’s sake (until I read that they’re porting Gutenberg for Drupal too… why why why?!); scrapping CMSes altogether in favor of just building sites with Bootstrap (and giving clients some rudimentary editing tools for the very few elements of their sites most of them actually modify post-launch); and even quitting the field entirely.

Frankly I don’t have the time or energy to make an extensive, coherent case for why Gutenberg is so fundamentally flawed; suffice to say it’s a combination of four main issues:

  1. frustrations over its excessive reliance on React (the Flash of the 2020s) for so much of its functionality,
  2. irritation at its embrace of the “make the interface seem simple by just hiding everything until the user hovers over the right magic spot” approach to UI/UX design,
  3. trying to get a handle on how the damn thing works, due to its combination of woefully inadequate and outdated documentation, and the fact that it is constantly changing, in ways that break my code (which was written based on earlier assumptions about how things worked, because that was all I had to go on), and
  4. its absolute, unforgivable abandonment of the core web design principle of separation of content and presentation.

The last one is really the killer, and it is only getting worse, because not only does the code — that fragile, convoluted, redundant code, stored in the database — become increasingly unmanageable the more you build your site, but WordPress is constantly pushing more of its structure into this disastrous framework (if you can call it a framework). The Site Editor is a true abomination that can’t possibly be useful to anyone… except possibly “no code” website builders. But honestly, if you can’t write code, you should just be using Squarespace instead of WordPress. You’ll be much happier, and so will your clients.

All of these issues probably stem from one even more basic to the whole discussion though: the creators of WordPress (especially imperious leader Matt Mullenweg) do not consider WordPress to be for what most of us “WordPress professionals” actually use it for. To them, it is blogging software. Period. But very few people who make a living in the WordPress ecosystem are using it to build blogs. Instead we are using it as a general-purpose CMS.

Gutenberg is adequate for a basic blog — in fact, I’m using it for this one, and I do prefer editing my posts in Gutenberg vs. Classic Editor. Its severe flaws and limitations don’t become readily apparent in the “basic blog” context.

There’s an argument to be made that Gutenberg really exists for WordPress.com to compete with the likes of Medium and Substack, and the industry of us web professionals who use the open source version are of no consequence to Matt’s vision for the platform.

Anyway, I have managed to launch about ten new client sites in the past year-plus using WordPress with Gutenberg, and every time I have had to face frustration and embarrassment as I acknowledge with clients the limitations of the tool, or sympathize with their frustrations in dealing with it as users.

My current project may be the last straw though. I’m two days away from launching the biggest site, by far, that I’ve built with Gutenberg. It’s over a year in the making, and now at the eleventh hour I am confronting the possibility of having to manually edit a huge number of posts in a CPT I created — and naively used the Block Editor to manage instead of just some ACF fields — because the client wants to change the default text sizes.

It’s possible this situation could be remedied by the merger of Block Patterns and Reusable Blocks that happened in WordPress 6.3, but guess what… we had already created all of this before that functionality was an option. I still haven’t had time to even figure out exactly what the implications of these 6.3 changes are, because I’ve been too busy just trying to build the site.

That’s where WordPress is really dying for me as a viable platform to work on. It’s supposed to be the foundation for what I do, but now the ground is constantly shifting beneath my feet. Gutenberg is making web development much harder and more frustrating, projects are taking longer, and it’s making me look incompetent and unprofessional to my clients. I’ve been a professional web developer since 1996; I’ve been using WordPress for projects since 2008, and almost exclusively since 2014. But now I don’t trust it anymore.

I’m in a position where I may (fingers crossed) be able to back off taking on any new freelance projects for the remainder of the year, once this site has launched. I am really hoping that’s the case, because it’s time for me to make a serious re-evaluation of whether or not I want to build any more WordPress sites in the future, and if not, I need to take that time to learn — or build — a new platform.

The great irony, of course, is that my business has increasingly been made up of selling and supporting my commercial WordPress plugin, ICS Calendar Pro. Fortunately, my work on that plugin has very little to do with, nor is significantly impacted by, the Gutenberg/Block Editor project, although that may change as WordPress continues to (d)evolve.

(Don’t even get me started on how bad Gutenberg is for responsive design.)

One document that encapsulates the Block Editor core team’s detachment from the reality of how most professionals actually use WordPress

That would be this document.

Establish early what content you expect to require updates

At a high level, it’s important to recognize that not every piece of content can be updated across the entire site and that the method of creation greatly impacts what’s possible. As a result, it’s critical to spend time ahead of creation determining what you expect to need updates and to put that content in the appropriate format. This will make a huge difference in terms of future maintenance.

Embrace theme design at the block level

Block theme design requires a mindset shift from the previous approach of designing large sections of a theme and controlling them via updates. While a holistic view of a design is still important when creating a custom theme project, blocks require that themers approach design on a more atomic level. This means starting from the block itself, typically through theme.json customizations. The goal is that each individual “atom” (i.e., block) can be moved around, edited, deleted, and put back together without the entire design falling apart.

The more that you approach design at the block level, the less need there is to propagate updates to things like patterns and templates across the entire site. If the atomic pieces are in place, their layout should not matter.

Gee that’s rich. My particular issue right now is that I need to make some updates to a block pattern I created for my client’s site. Unfortunately, that block pattern was already in use on about 40 pages of their site, but it involves an unanticipated design issue. (As it happens, yes I probably should have thought it through a bit more before it got propagated so extensively, but the practical reality of building websites is that sometimes you don’t know what will or will not be effective at the outset — especially when you’re simultaneously dealing with end users learning how to wrangle Gutenberg — and one of the great features of the web from its inception to today is that things are easy to change later on. In fact, that has been a driving force behind template-oriented CMS platforms from the beginning. It’s the separation of functionality, design and content that has been at the heart of most well-structured website editing platforms, including WordPress, until now.

It’s easy, when you believe that what you are creating is a blogging platform, that people only use it to create blog posts that are content-heavy with mostly one-off layouts. And yes, that’s how WordPress started. But the entire team must collectively have its heads deeply inserted up Matt Mullenweg’s ass (sorry for being crass, but I’m also being honest) if they think that’s how WordPress is predominantly used, if that’s what made WordPress as big as it is. Because it’s not.

I’ve been doing “block-based” design with WordPress sites (using Advanced Custom Fields and its wonderful Flexible Content field) since well before the Gutenberg project existed. But I had a much different, less “atomic” concept of blocks. This atomic approach is great (I guess) in concept, but it is too fine-grained to be a useful tool for the average web content editor, and it makes design and development orders of magnitude more difficult and time-consuming.

I have now completed four site projects using my own custom block-based theme, and have three more underway. While there are some really “cool” features of the Block Editor (Gutenberg), these projects have also taken me much longer and been far more maddening to build, and have left my clients much less confident in their ability to easily edit their content, than anything I had done in the previous decade of working primarily with WordPress.

And this last set of three projects is in many ways a rolling back of features, because after too many months of frustration with the limitations of block themes, “version 3” of my custom theme actually reverts from using the new HTML-based page templates to using PHP-based templates. It’s a regression in a way, but I never had any intention of using the Site Editor anyway, because it’s not an easier way for me to build sites, and it grants access to elements that should be 100% hands off for the clients who’ve hired me.

And now, once again, I’ve been derailed from my work by the need to spend 45 minutes venting my frustrations over this predicament in a blog post.

By the way, I'm aware of the irony of using Gutenberg in order to decry it, so don't bother pointing that out.


So… how did I end up resolving the issue of updating the block patterns that already appear in my content? Do you really want to know? I fired up phpMyAdmin, wrote a SQL query to find all of the affected instances, and manually copy-pasted the update into them. (Yes, I could’ve written a SQL statement that would just do the replacements; I tried that first, but the replacement text was really long and was generating a MySQL error that I couldn’t quickly pin down, so it was faster to just manually edit the 40 records.)

A simple way to add responsive (breakpoint-specific) blocks in Gutenberg

The new WordPress Block Editor (a.k.a. Gutenberg) has improved immensely over the years, to the point where I am now willingly (although occasionally grudgingly) using it as my main development platform for client sites.

One area where it really falls down though is in smartly handling responsive breakpoints. There is some effort to make it responsive-friendly (though it’s definitely not “mobile first”), but there are really weird holes, like the fact that there’s no built-in way to apply consistent left and right margins on text content at smaller screen sizes; once you’re below the defined content width, if you don’t manually configure your theme to add padding/margins to headings, paragraphs, etc., and they don’t have a defined background color, the text will bump right up against the edges of the screen.

That’s not the problem I’m here to solve at the moment, however. Instead, I want to focus on a handy little tool I’ve been using in my WordPress development for over a decade: specialized CSS classes to designate blocks of content as only appearing on phones, or not appearing on phones.

By “phone” here I just mean the smallest standard breakpoint. I’m using the WordPress convention (at least it used to be the WordPress convention; I don’t feel like I can trust anything anymore) of setting that at the slightly odd (although even) value of 782 pixels.

What can you do with this? Once you have CSS classes that designate a block as only appearing on phones or not appearing on phones, then you can easily tailor your output to certain screens. Obviously (at least, I hope it’s obvious) this is not the ideal solution; it means you’re delivering HTML content — potentially redundant HTML content — that will not be seen by some users. But nothing in web development is perfect, and this can be a convenient way to get out of a pinch when, for example, you have a very complex desktop layout element that simply cannot be adapted in a usable way on phones. You can just hide that element on the phone breakpoint and, if desired, present the same content in a more simplified way to only phones. (Again… only if you can’t achieve a usable phone experience on the same HTML block via media query-specific CSS.)

OK, let’s get down to it. The first thing you need to do is register a couple of block styles. I am only making these styles applicable to the Group block, because that seems like a logical way to rein it in. Any block can easily be wrapped in a group, so if you need this feature, just do it.

register_block_style('core/group', array(
  'name' => 'no-phone',
  'label' => 'No phone'
));

register_block_style('core/group', array(
  'name' => 'phone-only',
  'label' => 'Phone only'
));

That should go into your functions.php file or wherever in your theme you are defining block characteristics. Ideally it should be in a function that is executed on the init action. Next, you need to make sure you’ve got a custom block style .css file enqueued for the Group block. You can place this wherever is appropriate within your theme; I happen to have a nested assets/css/blocks folder where I put mine. Here’s that bit of code, also for your function that runs on init.

wp_enqueue_block_style('core/group', array(
  'handle' => 'my-theme-core-group',
  'path' => get_theme_file_path('assets/css/blocks/core-group.css'),
  'src' => get_theme_file_uri('assets/css/blocks/core-group.css'),
));

And then in the referenced core-group.css file, you’ll need this:

@media screen and (max-width: 782px) {	
  .wp-block-group.is-style-no-phone {
    display: none !important;
  }
}

@media screen and (min-width: 783px) {
  .wp-block-group.is-style-phone-only {
    display: none !important;
  }
}

Now in the Block Editor, when you switch to the Styles tab when focused on a Group block, you’ll see your new style options:

Some perspective on Gutenberg

Today I had to do some work on a client’s site that I didn’t build but have ended up maintaining, which is built from an amalgam of multiple “page builder” plugins, but most prominently, WP Bakery.

I was just explaining to my wife (who is not a developer but who uses WordPress, both Classic Editor and Gutenberg/Block Editor, extensively) what it’s like to use WP Bakery:

“Imagine the most annoying aspects of Gutenberg that you find the most annoying*, then imagine something ten times clunkier, a hundred times uglier, and a thousand times less intuitive. That’s WP Bakery.”

—Me

*Yes I really did, deliberately, say it that redundantly.

Vindication!

I already mentioned this in an addendum to my last blog post, but it seems to warrant its own dedicated post.

I’m a self-employed, solo developer, not very actively engaged in the WordPress “community” even though my work is 95% WordPress. So I have apparently missed the memo that shortcodes were (prior to yesterday’s release of WordPress 6.2.1, anyway) the way people were injecting PHP into their HTML-based Block Theme templates. (Silly me… I was just misusing Block Patterns to the same effect.)

Well… as it turns out, allowing shortcodes in Block Theme templates apparently was a security issue, which the WordPress core team summarily “fixed” by just outright removing shortcode support in templates in this update.

This change did break a pair of sites for me (which are still just in final testing, not live, and which I need to go fix as soon as I finish writing this), but the problem was relatively minor. It sounds like a lot of people are using shortcodes extensively as a backdoor hack for adding PHP functionality to templates, and they are… um… not happy.

At what point does the Gutenberg team collectively take a step back and realize that maybe they’ve been the ones Doing It Wrong™ all this time? I feel like that reckoning is approaching.