How can a system fundamentally evolve without drastically changing? WordPress can build incredible sites, yet the usability and clarity that used to be a driving force for its adoption has been fading away. The present reality is that many people struggle using WordPress as a tool for expression—they struggle to compose richer posts with media, to get their site looking the way they want, to imitate how a theme demo looks, or to set up and customize a store. There is a disconnect between what is edited in a given field somewhere in the interface with how it will look on the real site. WordPress has always been about the user experience, and that needs to continue to evolve under newer demands. Gutenberg is an attempt at fundamentally addressing those needs, based on the idea of content blocks. It’s an attempt to improve how users interact with their content in a fundamentally visual way, while at the same time giving developers the tools to create more fulfilling experiences for the people they are helping.

How can such a vision happen without dismantling, rebuilding, fragmenting, or breaking the WordPress ship that for over a decade has been carrying the thoughts, joys, and livelihoods of millions of people and more than a quarter of the web?

The ship, like Theseus’, needs to continue sailing while we upgrade the materials that make it. It needs to adapt to welcome new people, those that find it too rough to climb on board, too slippery a surface, too unwelcoming a sight, while retaining its essence of liberty. This is not an easy challenge—not in the slightest. Indeed, we called it Gutenberg for a reason, for both its challenges and opportunities, for what it can represent in terms of continuity and change. It is an ambitious project and it needs the whole WordPress community to succeed. I’d like to start examining some of the decisions made along the way, and the ones that are still to come.

Optimize for the user. An early overview for the project described some of the requirements it faced from a document and data structure perspective. Namely, how can we introduce the notion of content blocks in a way that is transparent to the existing ecosystem while allowing us to rapidly iterate on what ultimately matters the most—the user experience. This means being able to start using Gutenberg very early on without losing access to your content (opening it in other editors, for instance) and without changing how rendering the document works. The overall principle has been to let the machines do what they are good at. I won’t go into much detail here on the specific technical details because we have written about it in the project documentation and other blog posts. Honoring the user content as HTML is important: it assures their posts remain in a highly accessible way for the future and avoids platform lock-in.

On Guides and Placeholders. It is true that WordPress is capable of creating sophisticated sites and layouts. The issue is you need to know how to do it. And getting there requires a level of commitment and expertise that should be unnecessary. Why do users have to bear the weight of convoluted setups to work around the lack of a solid and intuitive visual experience?

This question is what brought us to the concept of blocks in the first place. The simplified nature of blocks, which optimizes for the direct manipulation of content and a single way to insert it, proposes an evolution of the WordPress model. It also comes with interesting opportunities. For example: how many themes have remarkable presentation in their demo sites but require Herculean efforts to replicate? A core ingredient of blocks is that, by their nature, they have a defined “empty state” that works as a placeholder describing how someone can interact with it. Blocks can guide a user as they craft their content intuitively. They are contextual tutorials that both show and teach how to add content. Here is an example of an image block that has no content:

On Templates. Imagine defining a whole page template as a set of default blocks, ready to be filled once the user creates a page; or a custom post type that specifies only certain blocks as available and has them already present in the page instead of a blank canvas. Imagine a simple site meant for publishing pictures where the default block can be just an image block, streamlining the process of creating content in the context of its purpose. On mobile this could reduce the time spent setting things up. This flexibility replaces one of the main needs for post formats, a long quest to allow more diversity of expression. That is, a UI that is contextual to the type of content being created. It also scales further into more advanced post types. A “book” block can include several distinct fields within the context of exactly how it will be presented. A business running an ecommerce plugin can set up pages with products and related blocks—while the users just have to fill in the fields. Finally, themes could now guide their users to the satisfaction of achieving the desired look, without ever leaving the composing interface.

A Powerful Design Tool. This is an important idea to clarify. Contrary to a worried perception that designs will be susceptible to breaking if the user can edit things, Gutenberg aims to give developers a way to define and protect structural markup and their design while giving users the ability to directly edit the information intuitively. Rather than making it easy to mess up a design by mistake or lack of knowledge, Gutenberg protects the design and guides the user. What used to require a mixture of widgets, opaque shortcodes, different meta-boxes, and an instruction sheet to follow—all without a direct visual indication of how things would end up looking—can now be done within a block that looks like the final result. The designer is able to create sophisticated layouts that users can interact with easily and directly without the fear of breaking things.

This puts more tools in the hands of developers and designers without alienating users. The benefit of direct manipulation is that there is no cognitive barrier to overcome—what you see is what you edit. Blocks can define what is editable and in which ways. Their markup cannot be ruined because the block is explicit about how the information will be presented. What used to require a complex set of abstractions can now become a simple structural block that is easy to edit, yet hard to break.

Themes can also provide styles for individual blocks, which can, in aggregation, fundamentally alter the visual appearance of the whole site. You can imagine themes becoming more about the presentation of blocks, while the functional parts can be extracted into blocks (which can potentially work across multiple theme variations). Themes can also provide templates for multiple kind of pages—colophon, products, portfolios, etc., by mixing blocks, setting them up as placeholders, and customizing their appearance.

Discovering Blocks. One of the goals of the block editor is to consolidate the different ways content can be created under the same interface pattern. This not only surfaces a lot of “hidden” features of WordPress but also opens new opportunities for the entire plugin ecosystem. Once the way a user creates content goes through a predictable interface flow, WordPress can surface optional plugins in the right context. If a user searches in the block inserter for something they want to add to their site, and a block doesn’t currently exist, we can immediately search for relevant plugins that might offer such blocks:

On the Layers of the Onion. In order to shift the content creation paradigm without breaking expectations, there are several layers of architecture working in tandem. There is a lot going on before Gutenberg finally outputs a block to the post. First, we get the raw content of the post; we then identify blocks through a grammar parser; we allocate additional attributes for a block based on different heuristics; we build a tree of block objects; we attempt to validate that the shape the block wants to output matches what we have; we finally pass the block type to a visual component which renders the edit context the block has specified when it was registered. All of this happens fast. Yet the different stages and isolated steps grants us a lot of possibilities. If you have already tested the Gutenberg plugin you might have seen a dialog like the following:

This occurs during the “validate what the block can save matches what we have” step. Gutenberg starts with a very strict baseline to allow us to iterate and build the layers we need for an optimal experience. This means if the markup for a paragraph block is lacking p tags, we can identify that as an error. There are three ways we currently offer to resolve it: let the block force what it expects overwriting extraneous markup; convert a block to “classic mode” which switches the block type to be handled by the classic WordPress editor (within Gutenberg); and transforming the block into an HTML block where you can write whatever markup is desired. This is a powerful mechanism and there’s a lot we can do with it. In future releases we’d want to display a before & after comparison for blocks where we detect changes above a certain threshold. Furthermore, these operations are isolated to the block, which gives a lot of granularity to further refine the experience with additional context.

Handling Multiple Sources. In addition to being able to validate blocks, we can also transform generic content into Gutenberg blocks. We are exploring these behaviours through the ability to paste arbitrary content into the editor. (Gutenberg optimizes pasting for several sources, like Google Docs, Microsoft Office, Apple Pages, older WordPress posts, and general web content). It also supports pasting plain text markdown and converting it to blocks. Since blocks are isolated, it is possible to mix different content types without risking the integrity of other blocks.

Markdown can often be great for writing, but it’s not necessarily the best environment for working with rich media and embeds. With the granularity afforded by blocks you could intermix markdown blocks with any other block, adapting to whatever is the most convenient way to express a specific kind of content. Whenever a block cannot be interpreted, we can also handle it as a plain HTML block. In future releases, you’d be able to edit individual blocks as HTML without having to switch the entire editor mode. Individual HTML blocks can also be previewed in place and immediately.

On Granularity. With the abstraction blocks provide, we can also build several tools that take advantage of the fact the full document is broken down into smaller units with semantic value. An example could be the document outline functionality that leverages the presence of heading blocks and allows the user to navigate through the document easily. It can also warn if it detects incorrect heading levels in the outline. Other plugins, like Yoast, could more surgically tailor their tools on a much smaller surface by focusing on single blocks at a time instead of having to deal with the entire document. This same granularity is allowing us to develop a collaborative editing framework where we can lock content being edited by a peer on per block basis, instead of having to lock down the whole post.

A Powerful Developer Tool. Gutenberg not only comes with several user-facing blocks, but the tools we use to create them and power their functionality are also available as components for others to build their own blocks. Our hope is that creating new blocks can be as easy as combining some of our tools, defining new markup and its presentation. This sharing of tools also ensures the user experience is more consistent. We might even look at building a “block composer” (block editor, if you will!) in the future where you can create custom blocks and package them for release. By reusing these pieces, the developer benefits from all the work that went behind them, including things like built in accessibility. These components can also take cues from themes— like the color palette component does—allowing the theme to overwrite the default colors.

Looking Beyond the Post. Gutenberg is initially focused on the post editor but the overarching plan is that it becomes the basis for general editing and customization in WordPress. There are features already in progress that expand beyond the content of the post. “Global Blocks” will allow a user to reuse a specific block (with its content) through multiple posts or pages. This absorbs some of the simpler needs that custom post types historically covered: a “testimonial” can become a simple Quote block that is now globally saved and accessible across all posts through the block inserter. Blocks are also able to save attributes in meta fields, if needed, granting continuity to existing features. Overall, the concept of the block is not about where it stores data, but how the user interacts with it. Blocks will also support nesting, opening further possibilities for customization.

Once Gutenberg is capable of handling all the pieces that visually compose a site—with themes providing styles for all the blocks—we end up with an editor that looks exactly like the front-end. (And at that point, we might just call it front-end editing.) Yet we’d had arrived at it through gradually improving the pieces of our familiar ship, in a way that didn’t cause it to collapse or alienated the people aboard. We want to accomplish this in a way that would allow us to refine and correct as we iterate and experience the reality of what is being built and how it is being used.

Gutenberg is about converting the need for discrete data from one of indirect manipulation into a direct and richer visual experience. It doesn’t seek to remove existing functionality—shortcodes still work the same way—but introduce new ways of interacting with the content. It is an attempt at improving how users can connect with their site in a visual way, not at removing the flexibility and power that has made WordPress thrive. There might be a time when the old ways become obsolete and disappear, absorbed by the richer and clearer interface of blocks, but we are doing as much as possible to make this a process. The old doesn’t have to disappear suddenly, it can be gradually shaped into the new.

Thank you to Mark Armstrong for his feedback and suggestions.