This article outlines how Gutenberg items need to be prepared and the technical requirements expected for this item type. This article is Part 6 of the requirements for WordPress Theme authors. WordPress is a large topic, so you will also need Parts 1 - 6 of the requirements below:
- WordPress Theme Requirements Part 1 - General
- WordPress Requirements Part 2 - Features
- WordPress Requirements Part 3 - Theme Plugins
- WordPress Requirements Part 4 - Coding
- WordPress Requirements Part 5 - Theme Security
- WordPress Requirements Part 6 - Gutenberg (you are here!)
If you are a Code author looking for more information on Wordpress Plugins to upload to a code category, please refer to the Plugin Requirements.
Theme Requirements
Mandatory
Following are the Gutenberg editor support requirements:
- Themes must ensure that all WordPress core blocks are styled to match the design of the theme/demos. You can choose to load the core block styles, but you may need to add additional styling to ensure it matches your design.
- Themes must not register blocks as that is plugin territory. If extra blocks are required, they must be added via an accompanying plugin. The plugin requirements must be followed.
- Themes must not blacklist blocks.
- Themes must ensure there are no console errors coming from their Gutenberg implementation (theme or plugin).
Strongly Recommended
It is strongly recommended that themes are optimized for Gutenberg (see below). Additionally, the following are recommended in order to provide a better user experience:
- Provide support for the .alignwide and .alignfull classes by declaring theme support for wide-images and styling these classes. More information.
- Add a color palette to the editor where appropriate, remembering to:
- Create the classes that apply the colors in different contexts. For example core blocks use "color" and "background-color" contexts, e.g.: .has-strong-red-color { color: red; } and .has-strong-red-background-color { background-color: red; }
- Use sensible defaults, rather than creating an infinite number of custom colors. Gist: https://gist.github.com/richtabor/d1de57fbd219f41427d40e2522941900
- Consider users who are not using Gutenberg and provide sensible fallbacks or alternatives wherever possible. Remember that any advertised functionality must be available to customers or your item may be disabled, so please be clear about any limitations.
Gutenberg Optimized Definition
Themes with the Gutenberg Optimised attribute turned on, or otherwise advertising themselves as optimized for Gutenberg, must do the following as a minimum:
- Make sure that the Gutenberg editor is styled to match the frontend output as closely as possible. This should include any fonts used and any dynamic styles coming from settings etc. More information.
- Change the editor widths to match the widths used in the theme as closely as possible. More information.
Plugin Requirements
Mandatory
- Plugins must ensure there are no console errors coming from their Gutenberg implementation.
- Blocks must define basic block styles that any theme can use when displaying the block on the front end.
- Gutenberg functions must be checked for existence before being called, in case the user is on a version of WordPress that does not include Gutenberg and they are not running the plugin version. For example, before calling register_block_type it's existence should be checked using:
if ( function_exists( 'register_block_type' ) )
- Blocks must use wp.i18n.__() to enable translations. Available functions for translations below:
wp.i18n.__()
wp.i18n._x()
wp.i18n._n()
wp.i18n._nx()
wp.i18n.sprintf()
-
Example:
// Deconstruct just the __ function from wp.i18n global object
const { __ } = wp.i18n;
// Just pass in the text to make it available for translation
__( 'This text can be translated' );
Gutenberg Optimized Definition
Plugins can be considered as optimised for Gutenberg if they do the following, where appropriate:
- Create blocks, whether a) for the user to enter content directly via the block or b) to output content created elsewhere via the plugin's functionality.
- Create equivalent blocks in Gutenberg for any shortcodes created by the plugin.
- Convert any metaboxes created by the plugin to blocks / controls in Gutenberg.
- Enqueue a specific Gutenberg stylesheet in order to match the editor styling to the frontend output as closely as possible (where the plugin outputs CSS on the front end).
- Integrate any editor screen controls/content seamlessly with Gutenberg.
If the Gutenberg Optimised attribute is turned on, the plugin must do all of the above that apply to their context.