We tried converting a bespoke website design in WordPress with Gutenberg

and this is what happened

Marie Manandise
Jun 18, 2018 · 20 min read
Photo by Iker Urteaga on Unsplash

This is what we asked Marie to do

I’m Simon, founder of Studio 24, a digital agency who create user-centered websites for our clients. I recently asked my WordPress Lead Developer Marie to research and test WordPress’s new Gutenberg editing system. The objective was to take a recent design and attempt to implement a few custom designed components in Gutenberg.


As far as we are concerned, we don’t think we are going to implement our bespoke website designs using the Gutenberg editor just yet. The main reasons are:

  • so much so that even the official docs are out of date,
  • a few important features are still in their infancy or missing (overriding default blocks, nesting blocks, etc)
  • we estimate it would more than double our dev and QA time
  • updating blocks already used in the content is complicated

The Gutenberg exercise

We have used WordPress for the vast majority of our projects in the past few years. Gutenberg, planned for release as part of WordPress 5.0, changes quite drastically the content editing experience and WordPress development.

More details on what we need to achieve and how we’ve done it so far

An important part of our job is implementing an interface that provides enough flexibility to create varied content but that is constrained enough to prevent breaking the design when editing a website.

Getting prepared — A skill set U-turn

I personally have 10 years experience developing WordPress custom themes and on occasion, plugins. WordPress development so far requires the following skill set: strong knowledge of HTML and CSS, moderate to advanced level of PHP, a little JavaScript will do. (Although I have built up a decent knowledge of JavaScript over the years).

‘Easing’ into it

Now before I enter into technical details, I can already tell you that I didn’t go far at all. After three days of work, I was ashamed to get back to the rest of the team with nothing to show to them. Here is what happened.

Whitelisting blocks

I thought I’d start with something simple. I wanted to reduce the number of blocks available by default, as many of them were not needed in our design. The Gutenberg handbook provides code for doing just that here: https://wordpress.org/gutenberg/handbook/extensibility/extending-blocks/#removing-blocks.

“These […] hooks are still being optimized, so this might change slightly in the future.”

🤔… The rest of the conversation are other developers suggesting their own solutions.

Removing block options

I then wanted to recycle the remaining blocks and restrict their options. For example, looking at the paragraph block I don’t want the users to pick colours or text size. These are defined in our bespoke design and we want to avoid inline CSS.

  1. The modifications illustrated so far are too limited for our purpose. It did give me enough info to modify a block title and category but that’s all I could manage. We can append/prepend fields to a block but there’s no easy way to remove options, unless we try to override the block methods altogether?

Building MY simple block (as opposed to ANY simple block)

So at this point, as I cannot remove all the options I need to remove from the paragraph block, I decide to write my own. This is my brief to myself:

  • the text needs be multiline (multiple paragraphs to be precise) and wrapped into a div with our own CSS classes,
  • there must be an option to add extra space before the block (more on that later).

The language barrier: what happened to localisation?

I can enter text in my new block but when I publish or update the page, the text has gone. Looking into the database, it hasn’t saved properly. I double-check my code against the original one — which was working fine when I did the course — I only changed a few minor things such as the name of the block.

The shared CSS delusion — Workload multiplication

At this stage I have a block that can be edited and has the right markup elements. Good! Next step: adding styles to it. I don’t want to use inline CSS. I know I can add a CSS file per block but this block shouldn’t need any specific CSS, the website’s global CSS (for typography and generic spacing) should do.

“Setting up the block styles for the back-end editing experience was more involved than any of us had anticipated. It’s very much like adding editor styles to the current TinyMCE editor, but some Gutenberg blocks have very specific classes that needed to be overridden.”

Laurel Fulford of ThemeShaper.com, the Automattic Theme Division

This led me to another realisation: when we design a block, we also need to design its user interface (implemented in JS) and QA the user interaction. That’s a significant addition to my workload. At the moment, Advanced Custom field takes care of the UI for us.

Feedback pains — the deprecated method

What happens after internal QA and when client give their feedback? Again, we need to amend our CSS for the front-end, and for the back-end.

Every time I wanted to preview edited block markup…

The spacing conundrum — more code planning

Whilst I was working out these technical difficulties, a lot of other considerations were brewing at the back of my mind. An important one was: how do I decide what is a stand-alone block or what is a component that I can re-use in multiple blocks? Can I nest components and blocks?

A lead paragraph block?
Top half of a webpage section

The final straw: the Block Inspector

I commented on my difficulties with CSS above but forgot to mention another issue I faced. WordPress provides a series of ‘components’ (in the sense of ‘React component’ to use in blocks). For example, the Toolbar component to hold controls for options above the block editing area, the Media Upload button for picking images from the media library, or the RichText component which allows multiline text input with a few extra controls.

The block inspector that appears on the right-hand side, under the ‘Block’ tab, when editing a Gutenberg block.

Things I knew I couldn’t achieve anyway

There are other things that I knew in advance I couldn’t achieve. I thought maybe workarounds or solutions would come up as I got used to Gutenberg development but you now know the story.

Advanced templating

As mentioned at the beginning we need advanced templates in the sense that:

  • templates need to apply not only to different post types but also sometimes to specific (singular) posts.

Optimal image sizes

Looking at the design for a bespoke ‘quote’ block below.

This is not Simon Jones

Teasers — Complex references to other posts with manual overrides

How do we implement the block of teasers below?

Teasers leading to other pages of content
  • By default each page title, permalink, excerpt and thumbnail are picked up dynamically based on the selected post objects
  • We often add the ability to override the default title, excerpt and thumbnail manually for each entry

Main conclusions

Gutenberg is still very much in development and it needs to at least stabilise before we attempt this exercise again.

Throughout this whole experience, I was always aware that my lack of achievement with this exercise might simply be down to my limited knowledge of Gutenberg and React (I think most of us developers have been through the experience of frustration and hatred for a tool or language until we mastered it).

Currently, the lack of good documentation makes using Gutenberg difficult and risky

I spent hours cross-referencing tutorials, blog posts and Issues from Github to implement the most fundamental things (internationalisation for example).

Steep increase in development and QA time

Were we to implement one of our current websites with Gutenberg now, we estimate that the extra CSS work required to style blocks in the editor and the complexity of updating block markup would more than double our development and QA time.

And maybe we’re simply not Gutenberg’s target audience

I am sure Gutenberg will greatly improve the experience of users who put their website together themselves and use themes provided by WordPress to do so.

Studio 24

Articles on digital technology from agency Studio 24

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store