Skip to content

Commit d36b40d

Browse files
ajlendeajlendefabiankaegyjuanmaguitaroandregal
authored
Update documentation for theme.json version 3 (#61221)
Co-authored-by: ajlende <[email protected]> Co-authored-by: fabiankaegy <[email protected]> Co-authored-by: juanmaguitar <[email protected]> Co-authored-by: oandregal <[email protected]>
1 parent ea74c4c commit d36b40d

File tree

12 files changed

+115
-88
lines changed

12 files changed

+115
-88
lines changed

‎docs/how-to-guides/curating-the-editor-experience/patterns.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,11 @@ With WordPress 6.0 themes can register patterns from [Pattern Directory](https:/
7979

8080
```json
8181
{
82-
"version": 2,
8382
"patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
8483
}
8584
```
8685

87-
Note that this field requires using [version 2 of theme.json](/docs/reference-guides/theme-json-reference/theme-json-living.md). The content creator will then find the respective Pattern in the inserter “Patterns” tab in the categories that match the categories from the Pattern Directory.
86+
The content creator will then find the respective Pattern in the inserter “Patterns” tab in the categories that match the categories from the Pattern Directory.
8887

8988
## Additional resources
9089

‎docs/how-to-guides/curating-the-editor-experience/theme-json.md

+6-10
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define
1010

1111
```json
1212
{
13-
"version": 2,
13+
"version": 3,
1414
"settings": {
1515
"color": {
1616
"customDuotone": true,
@@ -25,7 +25,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define
2525

2626
```json
2727
{
28-
"version": 2,
28+
"version": 3,
2929
"settings": {
3030
"color": {
3131
"duotone": [
@@ -54,8 +54,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define
5454

5555
```json
5656
{
57-
"schema": "https://schemas.wp.org/trunk/theme.json",
58-
"version": 2,
57+
"version": 3,
5958
"settings": {
6059
"color": {
6160
"custom": true,
@@ -89,8 +88,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define
8988

9089
```json
9190
{
92-
"schema": "https://schemas.wp.org/trunk/theme.json",
93-
"version": 2,
91+
"version": 3,
9492
"settings": {
9593
"color": {
9694
"custom": true,
@@ -132,8 +130,7 @@ Continuing the examples with duotone, this means you could allow full access to
132130

133131
```json
134132
{
135-
"schema": "https://schemas.wp.org/trunk/theme.json",
136-
"version": 2,
133+
"version": 3,
137134
"settings": {
138135
"color": {
139136
"custom": true,
@@ -178,8 +175,7 @@ When using theme.json in a block or classic theme, these settings will stop the
178175

179176
```json
180177
{
181-
"$schema": "http://schemas.wp.org/trunk/theme.json",
182-
"version": 2,
178+
"version": 3,
183179
"settings": {
184180
"layout": {
185181
"contentSize": "750px"

‎docs/how-to-guides/themes/global-settings-and-styles.md

+38-29
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Global Settings & Styles (theme.json)
22

3-
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. Then `theme.json` [evolved to a v2](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/) with WordPress 5.9 release. This page documents its format.
3+
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.
44

55
## Rationale
66

@@ -48,7 +48,7 @@ To address this need, we've started to experiment with CSS Custom Properties, ak
4848

4949
```json
5050
{
51-
"version": 2,
51+
"version": 3,
5252
"settings": {
5353
"color": {
5454
"palette": [
@@ -86,7 +86,7 @@ body {
8686

8787
```json
8888
{
89-
"version": 2,
89+
"version": 3,
9090
"settings": {
9191
"custom": {
9292
"line-height": {
@@ -115,7 +115,7 @@ This specification is the same for the three different origins that use this for
115115

116116
```json
117117
{
118-
"version": 2,
118+
"version": 3,
119119
"settings": {},
120120
"styles": {},
121121
"customTemplates": {},
@@ -125,10 +125,13 @@ This specification is the same for the three different origins that use this for
125125

126126
### Version
127127

128-
This field describes the format of the `theme.json` file. The current version is [v2](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/), [introduced in WordPress 5.9](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/). It also works with the current Gutenberg plugin.
128+
This field describes the format of the `theme.json` file. The latest version is [version 3](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/) introduced in WordPress 6.6.
129129

130-
If you have used [v1](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-v1/) previously, you don’t need to update the version in the v1 file to v2, as it’ll be [migrated](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/) into v2 at runtime for you.
130+
New versions are introduced when a breaking change needs to be made. This allows theme authors to choose when to opt-in to the breaking changes and migrate their theme.json files to the new format.
131131

132+
Older versions of `theme.json` are backwards-compatible and will continue to work with newer versions of WordPress and the Gutenberg plugin. However new features will be developed on the latest version.
133+
134+
Follow the instructions in [migrating to newer versions](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/) for details on updating to the latest version.
132135

133136
### Settings
134137

@@ -145,7 +148,7 @@ The settings section has the following structure:
145148

146149
```json
147150
{
148-
"version": 2,
151+
"version": 3,
149152
"settings": {
150153
"border": {
151154
"radius": false,
@@ -209,7 +212,7 @@ The settings section has the following structure:
209212

210213
```json
211214
{
212-
"version": 2,
215+
"version": 3,
213216
"settings": {
214217
"appearanceTools": false,
215218
"border": {
@@ -357,7 +360,7 @@ The naming schema for the classes and the custom properties is as follows:
357360

358361
```json
359362
{
360-
"version": 2,
363+
"version": 3,
361364
"settings": {
362365
"color": {
363366
"duotone": [
@@ -532,7 +535,7 @@ For example:
532535

533536
```json
534537
{
535-
"version": 2,
538+
"version": 3,
536539
"settings": {
537540
"custom": {
538541
"baseFont": 16,
@@ -577,7 +580,7 @@ Note that the name of the variable is created by adding `--` in between each nes
577580

578581
```json
579582
{
580-
"version": 2,
583+
"version": 3,
581584
"settings": {
582585
"color": {
583586
"custom": false
@@ -597,7 +600,7 @@ Note that the name of the variable is created by adding `--` in between each nes
597600

598601
```json
599602
{
600-
"version": 2,
603+
"version": 3,
601604
"settings": {
602605
"blocks": {
603606
"core/button": {
@@ -614,7 +617,7 @@ Note that the name of the variable is created by adding `--` in between each nes
614617

615618
```json
616619
{
617-
"version": 2,
620+
"version": 3,
618621
"settings": {
619622
"color": {
620623
"palette": [
@@ -682,7 +685,7 @@ Each block declares which style properties it exposes via the [block supports me
682685

683686
```json
684687
{
685-
"version": 2,
688+
"version": 3,
686689
"styles": {
687690
"border": {
688691
"radius": "value",
@@ -761,7 +764,7 @@ Each block declares which style properties it exposes via the [block supports me
761764

762765
```json
763766
{
764-
"version": 2,
767+
"version": 3,
765768
"styles": {
766769
"border": {
767770
"color": "value",
@@ -856,7 +859,7 @@ Styles found at the top-level will be enqueued using the `body` selector.
856859

857860
```json
858861
{
859-
"version": 1,
862+
"version": 3,
860863
"styles": {
861864
"color": {
862865
"text": "var(--wp--preset--color--primary)"
@@ -885,7 +888,7 @@ By default, the block selector is generated based on its name such as `.wp-block
885888

886889
```json
887890
{
888-
"version": 1,
891+
"version": 3,
889892
"styles": {
890893
"color": {
891894
"text": "var(--wp--preset--color--primary)"
@@ -972,7 +975,7 @@ If they're found in the top-level the element selector will be used. If they're
972975

973976
```json
974977
{
975-
"version": 1,
978+
"version": 3,
976979
"styles": {
977980
"typography": {
978981
"fontSize": "var(--wp--preset--font-size--normal)"
@@ -1066,7 +1069,7 @@ For example, this is how to provide styles for the existing `plain` variation fo
10661069

10671070
```json
10681071
{
1069-
"version": 2,
1072+
"version": 3,
10701073
"styles":{
10711074
"blocks": {
10721075
"core/quote": {
@@ -1103,7 +1106,7 @@ Within this field themes can list the custom templates present in the `templates
11031106

11041107
```json
11051108
{
1106-
"version": 2,
1109+
"version": 3,
11071110
"customTemplates": [
11081111
{
11091112
"name": "my-custom-template",
@@ -1132,7 +1135,7 @@ Currently block variations exist for "header" and "footer" values of the area te
11321135

11331136
```json
11341137
{
1135-
"version": 2,
1138+
"version": 3,
11361139
"templateParts": [
11371140
{
11381141
"name": "my-template-part",
@@ -1145,22 +1148,28 @@ Currently block variations exist for "header" and "footer" values of the area te
11451148

11461149
### patterns
11471150

1148-
<div class="callout callout-alert">Supported in WordPress from version 6.0 using <a href="https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/">version 2</a> of <code>theme.json</code>.</div>
1151+
<div class="callout callout-alert">Supported in WordPress from version 6.0.</div>
11491152

11501153
Within this field themes can list patterns to register from [Pattern Directory](https://wordpress.org/patterns/). The `patterns` field is an array of pattern `slugs` from the Pattern Directory. Pattern slugs can be extracted by the `url` in single pattern view at the Pattern Directory. For example in this url `https://wordpress.org/patterns/pattern/partner-logos` the slug is `partner-logos`.
11511154

11521155
```json
11531156
{
1154-
"version": 2,
1157+
"version": 3,
11551158
"patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
11561159
}
11571160
```
11581161

11591162
## Developing with theme.json
11601163

1161-
It can be difficult to remember the theme.json settings and properties while you develop, so a JSON scheme was created to help. The schema is available at https://schemas.wp.org/trunk/theme.json
1164+
It can be difficult to remember the theme.json settings and properties and which versions of WordPress support which settings while you develop, so it can be helpful to use the provided JSON schema for theme.json.
1165+
1166+
Many code editors support JSON schema and can provide help like tooltips, autocomplete, or schema validation right in your editor.
1167+
1168+
Theme.json schemas for each WordPress version are available at `https://schemas.wp.org/wp/{{version}}/theme.json`. For example a schema for WordPress 5.8 is available at `https://schemas.wp.org/wp/5.8/theme.json`. To ensure that you're only using features available to your users, it's best to use the oldest version that your theme supports.
1169+
1170+
The latest schema including all the latest changes from the Gutenberg plugin is available at `https://schemas.wp.org/trunk/theme.json`.
11621171

1163-
Code editors can pick up the schema and can provide help like tooltips, autocomplete, or schema validation in the editor. To use the schema in Visual Studio Code, add `"$schema": "https://schemas.wp.org/trunk/theme.json"` to the beginning of your theme.json file.
1172+
Check your editor's documentation for JSON schema support. In Visual Studio Code, for example, you need to add `"$schema": "https://schemas.wp.org/wp/x.x/theme.json"` as a top-level property of your theme.json file, but other editors may be configured differently.
11641173

11651174
![Example using validation with schema](https://developer.wordpress.org/files/2021/11/theme-json-schema-updated.gif)
11661175

@@ -1210,7 +1219,7 @@ For example:
12101219

12111220
```json
12121221
{
1213-
"version": 2,
1222+
"version": 3,
12141223
"settings": {
12151224
"custom": {
12161225
"lineHeight": {
@@ -1240,7 +1249,7 @@ A few notes about this process:
12401249

12411250
```json
12421251
{
1243-
"version": 2,
1252+
"version": 3,
12441253
"settings": {
12451254
"custom": {
12461255
"line--height": { // DO NOT DO THIS
@@ -1284,7 +1293,7 @@ body {
12841293

12851294
### Specificity for link colors provided by the user
12861295

1287-
In v1, when a user selected a link color for a specific block we attached a class to that block in the form of `.wp-element-<ID>` and then enqueued the following style:
1296+
In WordPress 5.8, when a user selected a link color for a specific block we attached a class to that block in the form of `.wp-element-<ID>` and then enqueued the following style:
12881297

12891298
```css
12901299
.wp-element-<ID> a { color: <USER_COLOR_VALUE> !important; }
@@ -1304,7 +1313,7 @@ For blocks that contain inner blocks, such as Group, Columns, Buttons, and Socia
13041313

13051314
```json
13061315
{
1307-
"version": 2,
1316+
"version": 3,
13081317
"settings": {
13091318
"spacing": {
13101319
"blockGap": true,

‎docs/how-to-guides/themes/theme-support.md

-1
Original file line numberDiff line numberDiff line change
@@ -442,7 +442,6 @@ Link support has been made stable as part of WordPress 5.8. It's `false` by defa
442442

443443
```json
444444
{
445-
"version": 1,
446445
"settings": {
447446
"color": {
448447
"link": true

‎docs/manifest.json

+8-2
Original file line numberDiff line numberDiff line change
@@ -582,7 +582,7 @@
582582
"parent": "reference-guides"
583583
},
584584
{
585-
"title": "Theme.json Version 3",
585+
"title": "Theme.json Version 3 Reference (latest)",
586586
"slug": "theme-json-living",
587587
"markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-living.md",
588588
"parent": "theme-json-reference"
@@ -594,7 +594,13 @@
594594
"parent": "theme-json-reference"
595595
},
596596
{
597-
"title": "Migrating to Newer Versions",
597+
"title": "Theme.json Version 2 Reference",
598+
"slug": "theme-json-v2",
599+
"markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v2.md",
600+
"parent": "theme-json-reference"
601+
},
602+
{
603+
"title": "Migrating Theme.json to Newer Versions",
598604
"slug": "theme-json-migrations",
599605
"markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-migrations.md",
600606
"parent": "theme-json-reference"

‎docs/reference-guides/README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@
3939

4040
## [Theme.json Reference](/docs/reference-guides/theme-json-reference/README.md)
4141

42-
- [Version 2 (living reference)](/docs/reference-guides/theme-json-reference/theme-json-living.md)
42+
- [Version 3 (latest)](/docs/reference-guides/theme-json-reference/theme-json-living.md)
43+
- [Version 2](/docs/reference-guides/theme-json-reference/theme-json-v2.md)
4344
- [Version 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md)
4445
- [Migrating to Newer Versions](/docs/reference-guides/theme-json-reference/theme-json-migrations.md)
4546

‎docs/reference-guides/theme-json-reference/README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
22

33
This reference guide lists the settings and style properties defined in the theme.json schema. See the [theme.json how to guide](/docs/how-to-guides/themes/global-settings-and-styles.md) for examples and guide on how to use the theme.json file in your theme.
44

5-
- [Version 2 (living reference)](/docs/reference-guides/theme-json-reference/theme-json-living.md)
5+
- [Version 3 (latest)](/docs/reference-guides/theme-json-reference/theme-json-living.md)
66

77
## Older versions
88

99
- [Migrating to Newer Theme.json Versions](/docs/reference-guides/theme-json-reference/theme-json-migrations.md)
1010
- [Version 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md)
11+
- [Version 2](/docs/reference-guides/theme-json-reference/theme-json-v2.md)

0 commit comments

Comments
 (0)