Skip to content

Commit

Permalink
Update theme.json docs for WordPress 5.8 (#33131)
Browse files Browse the repository at this point in the history
  • Loading branch information
@nosolosw
nosolosw committed Jul 2, 2021
1 parent 180abaf commit 3938f14
Showing 1 changed file with 144 additions and 12 deletions.
156 changes: 144 additions & 12 deletions docs/how-to-guides/themes/theme-json.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
# Global Settings & Styles (theme.json)

<div class="callout callout-alert">
These features are still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please share your feedback in the weekly #core-editor or #fse-outreach-experiment channels in Slack, or async in GitHub issues.
</div>

This is documentation for the current direction and work in progress about how themes can hook into the various sub-systems that the Block Editor provides.
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
Expand Down Expand Up @@ -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 and it's used to detect different versions and migrate them to the latest format.
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 %}

```json
{
"version": 1,
"settings": {
"color": {
"custom": true,
"customGradient": true,
"duotone": [],
"gradients": [],
"link": false,
"palette": []
},
"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,
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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">
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,
Expand Down Expand Up @@ -507,7 +629,7 @@ Each block declares which style properties it exposes via the [block supports me
"border": {},
"color": {},
"spacing": {},
"typography": {},
"typography": {}
},
"h1": {},
"h2": {},
Expand All @@ -532,12 +654,14 @@ Each block declares which style properties it exposes via the [block supports me
"h6": {}
}
},
"etc": {}
"etc": {}
}
}
}
```

{% end%}

### Top-level styles

Styles found at the top-level will be enqueued using the `body` selector.
Expand Down Expand Up @@ -702,6 +826,10 @@ h3 {

### customTemplates

<div class="callout callout-alert">
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.
Expand All @@ -727,6 +855,10 @@ Within this field themes can list the custom templates present in the `block-tem

### templateParts

<div class="callout callout-alert">
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.
Expand Down

0 comments on commit 3938f14

Please sign in to comment.