Using Gutenberg in Real World Projects

Gutenberg is slowly marching towards a releasable version but has anyone tested it on a real world project? There have been a few announced but nothing significant (that I’ve seen). I’ve integrated it into a couple of themes, and mostly it’s worked well, but the process is not straightforward.

So, I was interested to read this article by Marie from Studio 24 where she showcases the process and issues she found when trying to convert a design into an editable WordPress website.

Marie found a lot of issues with Gutenberg; but the most prominent for me is that there is a lot of documentation that is either lacking in detail or out of date.

Gutenberg needs to get developers onside. Many of the projects most vocal opponents are developers, so I think they should be focusing on improving the experience for the developers who want Gutenberg to succeed.

But Gutenberg is a very different project. Not like any previous WordPress one and so what we know already is no longer useful; which means good documentation is essential.


When I started using WordPress the WordPress Codex was a lifeline. It had documentation on how to use everything and that helped me massively. There needs to be a Gutenberg equivalent. The current Gutenberg handbook is a start, but it doesn’t cover half of what is needed.

Last week I asked the team for some documentation on how to use a feature that I knew should be there, and I was pointed to a Github ticket, and given some info on Twitter, that showed me the javascript command needed.

There was no mention of what hook to enqueue the code on, or if it needed to be wrapped in some sort of document ready script. I’m reasonably competent when it comes to WordPress but the feedback was very vague. It was frustrating and reminded me of Brad Frosts article about saying Just.

They have now added a code reference for my request to the Gutenberg handbook, however it’s still just the command with no implementation details.

Of course – documentation wasn’t the only takeaway from this article. There’s issues with localization, and editor styling, and customizing the editor, and all sorts. It’s well worth checking out.

As usual we have the standard disclaimer, Gutenberg is still in development and hopefully a lot of these will be fixed, but I stand by the fact that if the documentation was more comprehensive, and kept up to date, then we would be seeing more cool things built with it. Which should mean we would be seeing more positive articles (like this glowing one on the Tavern).

Let me know what you think on Mastodon, or BlueSky (or Twitter X if you must).

Link to this page

Thanks for reading. I'd really appreciate it if you'd link to this page if you mention it in your newsletter or on your blog.

WordPress News

The latest WordPress updates from the WPBriefs Podcast.

Related Posts

28 Sep 2018

Gutenberg Cloud – the Ultimate Open Source Project?

Gutenberg Cloud is a project for creating open source Gutenberg Blocks that work with both Drupal and WordPress that is created by web agency Frontkom.The team at Frontkom made a version of Gutenberg that works with Drupal. Since Gutenberg is...
27 May 2013

WordPress: 10 Years Young, What Does The Future Hold?

WordPress is now 10 years old. I started using wordpress 9 years ago – which means I joined the WordPress community early on. The reason I chose WordPress is simply because of the fabled 5 minute install process – I...
21 Oct 2018

Contributing to WordPress

In this article for WPTavern Chris Van Patten shares his experience with contributing to the Gutenberg project. The original article was a Twitter thread, but it’s nicer reading a proper long form piece.For Chris, the experience of contributing to Gutenberg...
01 Mar 2019

Open Source Sustainability

A lot of the internet is powered by open source technology. WordPress being a perfect example. This article looks at the practices behind open source development and considers just how sustainable it all is.One story looks at OpenSSL and how...
26 Sep 2018

WordPress get_post_gallery() Gutenberg Polyfill

I’m working on a new WordPress theme designed for Gutenberg, however Gutenberg isn’t finished, and there are elements that won’t work until the plugin is merged with core.One such issue, that I ran into this weekend, is that get_post_gallery() doesn’t...
10 Aug 2018

Gutenberg Reactions: Mixed Feedback?

WordPress 4.9.8 was released last week and Gutenberg plugin installations have rocketed because of the ‘try Gutenberg’ prompt that was included. This post on WPCouple shows some of the fantastic positive reactions Gutenberg has received.Of course, it’s not all rosey....