Update theme.json docs for WordPress 5.8
#33131
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,6 @@ | ||
| # Global Settings & Styles (theme.json) | ||
|
|
||
| WordPress 5.8 comes with [a new mechanism](https://make.wordpress.org/core/2021/06/25/introducing-theme-json-in-wordpress-5-8/) to configure the editor that enables a finer-grained control and introduces the first step in managing styles for future WordPress releases: the `theme.json` file. This page documents its format. | ||
|
|
||
| - Rationale | ||
| - Settings for the block editor | ||
|
|
@@ -152,12 +146,68 @@ This specification is the same for the three different origins that use this for | |
|
|
||
| ### Version | ||
|
|
||
| This field describes the format of the `theme.json` file. The current and only version is 1. | ||
|
|
||
| WordPress 5.8 will ignore the contents of any `theme.json` whose version is not equals to the current. Should the Gutenberg plugin need it, it'll update the version and will add the corresponding migration mechanisms from older versions. | ||
|
|
||
| ### Settings | ||
|
|
||
| <div class="callout callout-alert"> | ||
| The Gutenberg plugin extends the settings available from WordPress 5.8, so they can be used with other WordPress versions and they go through a maturation process before being ported to core. | ||
|
|
||
| The tabs below show WordPress 5.8 supported settings and the ones supported by the Gutenberg plugin. | ||
| </div> | ||
|
|
||
| The settings section has the following structure: | ||
|
|
||
| {% codetabs %} | ||
| {% WordPress %} | ||
|
There was a problem hiding this comment. I thought about naming this "WordPress 5.8" instead. The reason I didn't was that I believe this text has to be a single string without spaces. When I introduced the "Input"/"Output" for sections like this one https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#css-custom-properties-presets-custom I have a vague memory of having used "theme.json"/"CSS styles" and that it was problematic. Will look it up to confirm. There was a problem hiding this comment. #28655 illustrates what happened when using spaces in the codetabs texts. |
||
|
|
||
| ```json | ||
| { | ||
| "version": 1, | ||
| "settings": { | ||
| "color": { | ||
| "custom": true, | ||
| "customGradient": true, | ||
| "duotone": [], | ||
| "gradients": [], | ||
| "link": false, | ||
| "palette": [] | ||
|
There was a problem hiding this comment. It may be helpful to define a preset like a color so people know how to do it. There was a problem hiding this comment. There's a section fully focused on presets. |
||
| }, | ||
| "custom": {}, | ||
| "layout": { | ||
| "contentSize": "800px", | ||
| "wideSize": "1000px" | ||
| }, | ||
| "spacing": { | ||
| "customMargin": false, | ||
| "customPadding": false, | ||
| "units": [ "px", "em", "rem", "vh", "vw" ] | ||
| }, | ||
| "typography": { | ||
| "customFontSize": true, | ||
| "customLineHeight": false, | ||
| "dropCap": true, | ||
| "fontSizes": [] | ||
| }, | ||
| "blocks": { | ||
| "core/paragraph": { | ||
| "color": {}, | ||
| "custom": {}, | ||
| "layout": {}, | ||
| "spacing": {}, | ||
| "typography": {} | ||
| }, | ||
| "core/heading": {}, | ||
| "etc": {} | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| {% Gutenberg %} | ||
|
|
||
| ```json | ||
| { | ||
| "version": 1, | ||
|
|
@@ -213,7 +263,7 @@ The settings section has the following structure: | |
| } | ||
| ``` | ||
|
|
||
| {% end %} | ||
|
|
||
| Each block can configure any of these settings separately, providing a more fine-grained control over what exists via `add_theme_support`. The settings declared at the top-level affect to all blocks, unless a particular block overwrites it. It's a way to provide inheritance and configure all blocks at once. | ||
|
|
||
|
|
@@ -403,7 +453,6 @@ body { | |
| .wp-block-group.has-white-border-color { border-color: #444 !important; } | ||
|
|
||
| ``` | ||
| {% end %} | ||
|
|
||
| To maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. If the `theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`. | ||
|
|
@@ -462,8 +511,81 @@ Note that the name of the variable is created by adding `--` in between each nes | |
|
|
||
| ### Styles | ||
|
|
||
| <div class="callout callout-alert"> | ||
|
There was a problem hiding this comment. This would be styled as a callout. |
||
| The Gutenberg plugin extends the styles available from WordPress 5.8, so they can be used with other WordPress versions and they go through a maturation process before being ported to core. | ||
|
|
||
| The tabs below show WordPress 5.8 supported styles and the ones supported by the Gutenberg plugin. | ||
| </div> | ||
|
|
||
| Each block declares which style properties it exposes via the [block supports mechanism](../block-api/block-supports.md). The support declarations are used to automatically generate the UI controls for the block in the editor. Themes can use any style property via the `theme.json` for any block ― it's the theme's responsibility to verify that it works properly according to the block markup, etc. | ||
|
|
||
| {% codetabs %} | ||
|
|
||
| {% WordPress %} | ||
|
|
||
| ```json | ||
| { | ||
| "version": 1, | ||
| "styles": { | ||
| "color": { | ||
| "background": "value", | ||
| "gradient": "value", | ||
| "text": "value" | ||
| }, | ||
| "spacing": { | ||
| "margin": { | ||
| "top": "value", | ||
| "right": "value", | ||
| "bottom": "value", | ||
| "left": "value" | ||
| }, | ||
| "padding": { | ||
| "top": "value", | ||
| "right": "value", | ||
| "bottom": "value", | ||
| "left": "value" | ||
| } | ||
| }, | ||
| "typography": { | ||
| "fontSize": "value", | ||
| "lineHeight": "value" | ||
| }, | ||
| "elements": { | ||
| "link": { | ||
| "color": {}, | ||
| "spacing": {}, | ||
| "typography": {} | ||
| }, | ||
| "h1": {}, | ||
| "h2": {}, | ||
| "h3": {}, | ||
| "h4": {}, | ||
| "h5": {}, | ||
| "h6": {} | ||
| }, | ||
| "blocks": { | ||
| "core/group": { | ||
| "color": {}, | ||
| "spacing": {}, | ||
| "typography": {}, | ||
| "elements": { | ||
| "link": {}, | ||
| "h1": {}, | ||
| "h2": {}, | ||
| "h3": {}, | ||
| "h4": {}, | ||
| "h5": {}, | ||
| "h6": {} | ||
| } | ||
| }, | ||
| "etc": {} | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| {% Gutenberg %} | ||
|
|
||
| ```json | ||
| { | ||
| "version": 1, | ||
|
|
@@ -507,7 +629,7 @@ Each block declares which style properties it exposes via the [block supports me | |
| "border": {}, | ||
| "color": {}, | ||
| "spacing": {}, | ||
| "typography": {} | ||
| }, | ||
| "h1": {}, | ||
| "h2": {}, | ||
|
|
@@ -532,12 +654,14 @@ Each block declares which style properties it exposes via the [block supports me | |
| "h6": {} | ||
| } | ||
| }, | ||
| "etc": {} | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| {% end%} | ||
|
|
||
| ### Top-level styles | ||
|
|
||
| Styles found at the top-level will be enqueued using the `body` selector. | ||
|
|
@@ -702,6 +826,10 @@ h3 { | |
|
|
||
| ### customTemplates | ||
|
|
||
| <div class="callout callout-alert"> | ||
|
There was a problem hiding this comment. This would be styled as a callout. |
||
| This field is only allowed when the Gutenberg plugin is active. In WordPress 5.8 will be ignored. | ||
| </div> | ||
|
|
||
| Within this field themes can list the custom templates present in the `block-templates` folder. For example, for a custom template named `my-custom-template.html`, the `theme.json` can declare what post types can use it and what's the title to show the user: | ||
|
|
||
| - name: mandatory. | ||
|
|
@@ -727,6 +855,10 @@ Within this field themes can list the custom templates present in the `block-tem | |
|
|
||
| ### templateParts | ||
|
|
||
| <div class="callout callout-alert"> | ||
|
There was a problem hiding this comment. This would be styled as a callout. |
||
| This field is only allowed when the Gutenberg plugin is active. In WordPress 5.8 will be ignored. | ||
| </div> | ||
|
|
||
| Within this field themes can list the template parts present in the `block-template-parts` folder. For example, for a template part named `my-template-part.html`, the `theme.json` can declare the area term for the template part entity which is responsible for rendering the corresponding block variation (Header block, Footer block, etc.) in the editor. Defining this area term in the json will allow the setting to persist across all uses of that template part entity, as opposed to a block attribute that would only affect one block. Defining area as a block attribute is not recommended as this is only used 'behind the scenes' to aid in bridging the gap between placeholder flows and entity creation. | ||
|
|
||
| Currently block variations exist for "header" and "footer" values of the area term, any other values and template parts not defined in the json will default to the general template part block. Variations will be denoted by specific icons within the editor's interface, will default to the corresponding semantic HTML element for the wrapper (this can also be overridden by the `tagName` attribute set on the template part block), and will contextualize the template part allowing more custom flows in future editor improvements. | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This would be styled as a callout.