WordPress.org

Introducing a new way to WordPress

A new publishing experience for WordPress is in the works: get ready to make your words, pictures, and layout look as good on screen as they do in your imagination, without any code.

You might have heard of this project — it’s called Gutenberg, after another invention that revolutionized publishing — but are wondering what it means for you. Who will see the biggest difference, and what it will change for your everyday workflows? Everyone, and everything. The Gutenberg editor uses blocks to create all types of content, replacing a half-dozen inconsistent ways of customizing WordPress, bringing it in line with modern coding standards, and aligning with open web initiatives. These content blocks transform how users, developers, and hosts interact with WordPress to make building rich web content easier and more intuitive, democratizing publishing — and work — for everyone, regardless of technical ability.

It’s great that so many people think WordPress is the best way to get their ideas on the web, and it’s easy to unlock the power of WordPress if you know how to write code — but not everyone does. And now, you won’t need to.

Discover the new experience

The main Gutenberg editing interface

We want as much feedback and real-world testing of the experience as possible, so we’ve released it as a plugin for anyone to try. To experience this new way to work with WordPress, head to your site’s Dashboard and go to the Plugins menu item. Click on Add New, and type “Gutenberg” in the search box.

Alternately, you can download the Gutenberg plugin and upload it to your site.

Help build the future

Gutenberg is being developed on GitHub, and this documentation is a great place to start getting to know the project.

The team is eager to hear about your experience with Gutenberg! This is an exciting chance to have a real impact on the future of WordPress. Explore and use Gutenberg, then share you thoughts – use it to send feedback as many times as you want.

The most targeted way to help the people building this new user experience is to test the editor using a particular script and set of tasks. You can find the tests and instructions right here.

What is a block?

One of the things you hear a lot about during discussions of Gutenberg are blocks. These blocks are a unified way to style content that currently requires shortcodes, embeds, widgets, post formats, custom post types, theme options, meta-boxes, and other formatting elements. By allowing rich customization without deep knowledge of code, blocks make good on the promise of WordPress: broad functionality with a clear, consistent user experience.

The current WordPress editor is an open text window—it’s always been a wonderful blank canvas for writing, but when it comes to building posts and pages with images, multimedia, embedded content from social media, polls, and other elements, it required a mix of different approaches that were not always intuitive:

  • Media library/HTML for images, multimedia and approved files.
  • Pasted links for embeds.
  • Shortcodes for specialized assets from plugins.
  • Featured images for the image at the top of a post or page.
  • Excerpts for subheads.
  • Widgets for content on the side of a page.

As we thought about these uses and how to make them obvious and consistent, we began to embrace the concept of “blocks.” All of the above items could be blocks: easy to search and understand, and easy to dynamically shift around the page. The block concept is very powerful, and if designed thoughtfully, can offer an outstanding editing and publishing experience.

Imagine a custom “employee” block that a client can drag to an About page to automatically display a picture, name, and bio. A whole universe of plugins that all extend WordPress in the same way. Simplified menus and widgets. Users who can instantly understand and use WordPress — and 90% of plugins.

The stages of Gutenberg

Gutenberg has three planned stages. The first, aimed for inclusion in WordPress 5.0, focuses on the post editing experience and the implementation of blocks. This initial phase focuses on a content-first approach. The use of blocks, as detailed above, allows you to focus on how your content will look without the distraction of other configuration options. This ultimately will help all users present their content in a way that is engaging, direct, and visual.

These foundational elements will pave the way for stages two and three, planned for the next year, to go beyond the post into page templates and ultimately, full site customization.

Gutenberg is a big change, and there will be ways to ensure that existing functionality (like shortcodes and meta-boxes) continue to work while allowing developers the time and paths to transition effectively. Ultimately, it will open new opportunities for plugin and theme developers to better serve users through a more engaging and visual experience that takes advantage of a toolset supported by Core.

Compatibility

The Gutenberg project is actively addressing compatibility concerns. Blocks are the de facto new mechanism for building content features, and we recommend that developers migrate any features they offer that are well-encapsulated by blocks. However, support for existing WordPress functionality will remain, and there will be transition paths for shortcodes, meta-boxes, and Custom Post Types:

  • Shortcodes.
    • Will continue working without changes.
    • There is a new “shortcode block” to help inserting them.
    • There’s a planned mechanism for previewing them in place.
  • Meta-boxes.
    • Some will continue to work with no changes under the new UI.
    • Some will need updates (particularly those that rely on the DOM for operating).*
    • Several can be converted to native blocks (particularly those that are rendered on the front-end).
    • Some can transition to new Gutenberg native extension points outside of the content area.
    • There will be a mechanism for conflicting meta-boxes to load the classic editor instead with a notice.
  • Custom Post Types.
    • Are supported by Gutenberg.
    • Need REST API (show_in_rest) declaration.
    • Can opt out by not declaring “editor” support.
    • Will be able to declare supported and default blocks.

* Certain meta-boxes that rely on the specific structure of the current editing screen are not guaranteed to work under Gutenberg, and might need changes before they can be loaded correctly.

Finally, there is an officially supported plugin for disabling Gutenberg entirely.

Resources

There are a number of resources where you can learn more about the project and ideas behind it.