From 9582a1ba94eba62cd8ba7f85c8e2cfb8c480ac79 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:01:47 -0500 Subject: [PATCH 01/22] Update references to theme.json "version" in docs --- .../patterns.md | 1 - .../theme-json.md | 16 +++---- .../themes/global-settings-and-styles.md | 44 +++++++++---------- docs/how-to-guides/themes/theme-support.md | 1 - 4 files changed, 28 insertions(+), 34 deletions(-) diff --git a/docs/how-to-guides/curating-the-editor-experience/patterns.md b/docs/how-to-guides/curating-the-editor-experience/patterns.md index fbe5143298cdb..08b809bab9979 100644 --- a/docs/how-to-guides/curating-the-editor-experience/patterns.md +++ b/docs/how-to-guides/curating-the-editor-experience/patterns.md @@ -79,7 +79,6 @@ With WordPress 6.0 themes can register patterns from [Pattern Directory](https:/ ```json { - "version": 2, "patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ] } ``` diff --git a/docs/how-to-guides/curating-the-editor-experience/theme-json.md b/docs/how-to-guides/curating-the-editor-experience/theme-json.md index d373e0e81e345..d14f29e0a76f3 100644 --- a/docs/how-to-guides/curating-the-editor-experience/theme-json.md +++ b/docs/how-to-guides/curating-the-editor-experience/theme-json.md @@ -10,7 +10,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define ```json { -"version": 2, + "version": 3, "settings": { "color": { "customDuotone": true, @@ -25,7 +25,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define ```json { - "version": 2, + "version": 3, "settings": { "color": { "duotone": [ @@ -54,8 +54,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define ```json { - "schema": "https://schemas.wp.org/trunk/theme.json", - "version": 2, + "version": 3, "settings": { "color": { "custom": true, @@ -89,8 +88,7 @@ Since theme.json acts as a configuration tool, there are numerous ways to define ```json { - "schema": "https://schemas.wp.org/trunk/theme.json", - "version": 2, + "version": 3, "settings": { "color": { "custom": true, @@ -132,8 +130,7 @@ Continuing the examples with duotone, this means you could allow full access to ```json { - "schema": "https://schemas.wp.org/trunk/theme.json", - "version": 2, + "version": 3, "settings": { "color": { "custom": true, @@ -178,8 +175,7 @@ When using theme.json in a block or classic theme, these settings will stop the ```json { - "$schema": "http://schemas.wp.org/trunk/theme.json", - "version": 2, + "version": 3, "settings": { "layout": { "contentSize": "750px" diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md index 37f0ee8951c3c..0e806fb6388dd 100644 --- a/docs/how-to-guides/themes/global-settings-and-styles.md +++ b/docs/how-to-guides/themes/global-settings-and-styles.md @@ -48,7 +48,7 @@ To address this need, we've started to experiment with CSS Custom Properties, ak ```json { - "version": 2, + "version": 3, "settings": { "color": { "palette": [ @@ -86,7 +86,7 @@ body { ```json { - "version": 2, + "version": 3, "settings": { "custom": { "line-height": { @@ -115,7 +115,7 @@ This specification is the same for the three different origins that use this for ```json { - "version": 2, + "version": 3, "settings": {}, "styles": {}, "customTemplates": {}, @@ -145,7 +145,7 @@ The settings section has the following structure: ```json { - "version": 2, + "version": 3, "settings": { "border": { "radius": false, @@ -209,7 +209,7 @@ The settings section has the following structure: ```json { - "version": 2, + "version": 3, "settings": { "appearanceTools": false, "border": { @@ -357,7 +357,7 @@ The naming schema for the classes and the custom properties is as follows: ```json { - "version": 2, + "version": 3, "settings": { "color": { "duotone": [ @@ -532,7 +532,7 @@ For example: ```json { - "version": 2, + "version": 3, "settings": { "custom": { "baseFont": 16, @@ -577,7 +577,7 @@ Note that the name of the variable is created by adding `--` in between each nes ```json { - "version": 2, + "version": 3, "settings": { "color": { "custom": false @@ -597,7 +597,7 @@ Note that the name of the variable is created by adding `--` in between each nes ```json { - "version": 2, + "version": 3, "settings": { "blocks": { "core/button": { @@ -614,7 +614,7 @@ Note that the name of the variable is created by adding `--` in between each nes ```json { - "version": 2, + "version": 3, "settings": { "color": { "palette": [ @@ -682,7 +682,7 @@ Each block declares which style properties it exposes via the [block supports me ```json { - "version": 2, + "version": 3, "styles": { "border": { "radius": "value", @@ -761,7 +761,7 @@ Each block declares which style properties it exposes via the [block supports me ```json { - "version": 2, + "version": 3, "styles": { "border": { "color": "value", @@ -856,7 +856,7 @@ Styles found at the top-level will be enqueued using the `body` selector. ```json { - "version": 1, + "version": 3, "styles": { "color": { "text": "var(--wp--preset--color--primary)" @@ -885,7 +885,7 @@ By default, the block selector is generated based on its name such as `.wp-block ```json { - "version": 1, + "version": 3, "styles": { "color": { "text": "var(--wp--preset--color--primary)" @@ -972,7 +972,7 @@ If they're found in the top-level the element selector will be used. If they're ```json { - "version": 1, + "version": 3, "styles": { "typography": { "fontSize": "var(--wp--preset--font-size--normal)" @@ -1066,7 +1066,7 @@ For example, this is how to provide styles for the existing `plain` variation fo ```json { - "version": 2, + "version": 3, "styles":{ "blocks": { "core/quote": { @@ -1103,7 +1103,7 @@ Within this field themes can list the custom templates present in the `templates ```json { - "version": 2, + "version": 3, "customTemplates": [ { "name": "my-custom-template", @@ -1132,7 +1132,7 @@ Currently block variations exist for "header" and "footer" values of the area te ```json { - "version": 2, + "version": 3, "templateParts": [ { "name": "my-template-part", @@ -1151,7 +1151,7 @@ Within this field themes can list patterns to register from [Pattern Directory]( ```json { - "version": 2, + "version": 3, "patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ] } ``` @@ -1210,7 +1210,7 @@ For example: ```json { - "version": 2, + "version": 3, "settings": { "custom": { "lineHeight": { @@ -1240,7 +1240,7 @@ A few notes about this process: ```json { - "version": 2, + "version": 3, "settings": { "custom": { "line--height": { // DO NOT DO THIS @@ -1304,7 +1304,7 @@ For blocks that contain inner blocks, such as Group, Columns, Buttons, and Socia ```json { - "version": 2, + "version": 3, "settings": { "spacing": { "blockGap": true, diff --git a/docs/how-to-guides/themes/theme-support.md b/docs/how-to-guides/themes/theme-support.md index edf4b8e505c13..e5d6c34e4081c 100644 --- a/docs/how-to-guides/themes/theme-support.md +++ b/docs/how-to-guides/themes/theme-support.md @@ -442,7 +442,6 @@ Link support has been made stable as part of WordPress 5.8. It's `false` by defa ```json { - "version": 1, "settings": { "color": { "link": true From 90969f078f0317721d453ab3e49394018a325040 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:03:38 -0500 Subject: [PATCH 02/22] Add theme-json-v2 to manifest --- docs/manifest.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/manifest.json b/docs/manifest.json index 87ab88aa8cc54..37375bad0475b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -587,6 +587,12 @@ "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-living.md", "parent": "theme-json-reference" }, + { + "title": "Theme.json Version 2 Reference", + "slug": "theme-json-v2", + "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v2.md", + "parent": "theme-json-reference" + }, { "title": "Theme.json Version 1 Reference", "slug": "theme-json-v1", From 48f60824c1ff40deb4a6e617dc2cbeae081af747 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:03:58 -0500 Subject: [PATCH 03/22] Add theme-json-v2 to toc --- docs/toc.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/toc.json b/docs/toc.json index 713c55c8ee2b9..c0ec94fd049a0 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -250,6 +250,9 @@ { "docs/reference-guides/theme-json-reference/theme-json-v1.md": [] }, + { + "docs/reference-guides/theme-json-reference/theme-json-v2.md": [] + }, { "docs/reference-guides/theme-json-reference/theme-json-migrations.md": [] }, From 7b57d477358453b507375e03361d1ede4fddc0cb Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:04:57 -0500 Subject: [PATCH 04/22] Update title for v3 reference --- docs/manifest.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manifest.json b/docs/manifest.json index 37375bad0475b..c4e2193a68663 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -582,7 +582,7 @@ "parent": "reference-guides" }, { - "title": "Theme.json Version 3", + "title": "Theme.json Version 3 Reference (latest)", "slug": "theme-json-living", "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-living.md", "parent": "theme-json-reference" From 6191b6f43c41d6140e2e8582a16fe292bb0dd41d Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:05:18 -0500 Subject: [PATCH 05/22] Update title for theme json migrations --- docs/manifest.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manifest.json b/docs/manifest.json index c4e2193a68663..2780552ebc419 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -600,7 +600,7 @@ "parent": "theme-json-reference" }, { - "title": "Migrating to Newer Versions", + "title": "Migrating Theme.json to Newer Versions", "slug": "theme-json-migrations", "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-migrations.md", "parent": "theme-json-reference" From b2e8b30e608424187f6b2c1a21cc8953fb40554f Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:07:13 -0500 Subject: [PATCH 06/22] Remove reference to theme.json version for patterns --- docs/how-to-guides/curating-the-editor-experience/patterns.md | 2 +- docs/how-to-guides/themes/global-settings-and-styles.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/curating-the-editor-experience/patterns.md b/docs/how-to-guides/curating-the-editor-experience/patterns.md index 08b809bab9979..abb7d131041df 100644 --- a/docs/how-to-guides/curating-the-editor-experience/patterns.md +++ b/docs/how-to-guides/curating-the-editor-experience/patterns.md @@ -83,7 +83,7 @@ With WordPress 6.0 themes can register patterns from [Pattern Directory](https:/ } ``` -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. +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. ## Additional resources diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md index 0e806fb6388dd..c60adde23ee39 100644 --- a/docs/how-to-guides/themes/global-settings-and-styles.md +++ b/docs/how-to-guides/themes/global-settings-and-styles.md @@ -1145,7 +1145,7 @@ Currently block variations exist for "header" and "footer" values of the area te ### patterns -
Supported in WordPress from version 6.0 using version 2 of theme.json.
+
Supported in WordPress from version 6.0.
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`. From 5e45131690622a04cb68063c5017e620a8d350d3 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:09:17 -0500 Subject: [PATCH 07/22] Switch reference to theme.json version to wp version --- docs/how-to-guides/themes/global-settings-and-styles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md index c60adde23ee39..4667e89347658 100644 --- a/docs/how-to-guides/themes/global-settings-and-styles.md +++ b/docs/how-to-guides/themes/global-settings-and-styles.md @@ -1284,7 +1284,7 @@ body { ### Specificity for link colors provided by the user -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-` and then enqueued the following style: +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-` and then enqueued the following style: ```css .wp-element- a { color: !important; } From 06749cb1a437c8ce3b8c22b44ca3697f4633a954 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:10:53 -0500 Subject: [PATCH 08/22] Update living title in md --- docs/reference-guides/theme-json-reference/theme-json-living.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index bea655e61af82..3c557fc141a7f 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-living.md +++ b/docs/reference-guides/theme-json-reference/theme-json-living.md @@ -1,4 +1,4 @@ -# Theme.json Version 3 +# Theme.json Version 3 Reference (latest) > This is the living specification for **version 3** of `theme.json`. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin. > From 27030c3b13c29563aad27978cbef0eb52cd32a03 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:11:13 -0500 Subject: [PATCH 09/22] Fix wp version in living --- docs/reference-guides/theme-json-reference/theme-json-living.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index 3c557fc141a7f..e9902267a2e7f 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-living.md +++ b/docs/reference-guides/theme-json-reference/theme-json-living.md @@ -1,6 +1,6 @@ # Theme.json Version 3 Reference (latest) -> This is the living specification for **version 3** of `theme.json`. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin. +> This is the living specification for **version 3** of `theme.json`. This version works with WordPress 6.6 or later. > > There are some related documents that you may be interested in: > - the [theme.json v1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) specification, From 82e8abf15fc836f2c65c460ccb6b9b22d1afd6f0 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:12:28 -0500 Subject: [PATCH 10/22] Remove changes to v2 since 6.5 release --- .../theme-json-reference/theme-json-v2.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-v2.md b/docs/reference-guides/theme-json-reference/theme-json-v2.md index 56cdff1c3bb86..d30be1aa5107c 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-v2.md +++ b/docs/reference-guides/theme-json-reference/theme-json-v2.md @@ -28,9 +28,9 @@ Code editors can pick up the schema and can provide helpful hints and suggestion Setting that enables the following UI tools: -- background: backgroundImage, backgroundSize +- background: backgroundImage - border: color, radius, style, width -- color: link, heading, button, caption +- color: link - dimensions: aspectRatio, minHeight - position: sticky - spacing: blockGap, margin, padding @@ -40,8 +40,6 @@ Setting that enables the following UI tools: ### useRootPaddingAwareAlignments -_**Note:** Since WordPress 6.1._ - Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block. Please note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately. @@ -92,7 +90,6 @@ Settings related to colors. | text | boolean | true | | | heading | boolean | true | | | button | boolean | true | | -| caption | boolean | true | | --- @@ -103,7 +100,6 @@ Settings related to background. | Property | Type | Default | Props | | --- | --- | --- |--- | | backgroundImage | boolean | false | | -| backgroundSize | boolean | false | | --- @@ -180,7 +176,6 @@ Settings related to typography. | fluid | object, boolean | false | _{maxViewportWidth, minFontSize, minViewportWidth}_ | | letterSpacing | boolean | true | | | lineHeight | boolean | false | | -| textAlign | boolean | true | | | textColumns | boolean | false | | | textDecoration | boolean | true | | | writingMode | boolean | false | | @@ -263,7 +258,6 @@ Typography styles. | fontWeight | string, object | | | letterSpacing | string, object | | | lineHeight | string, object | | -| textAlign | string | | | textColumns | string | | | textDecoration | string, object | | | writingMode | string, object | | From e65c11ad1cf88abda14c130466544c4a23a86ef4 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:13:41 -0500 Subject: [PATCH 11/22] Update toc in md files --- docs/reference-guides/README.md | 3 ++- docs/reference-guides/theme-json-reference/README.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/README.md b/docs/reference-guides/README.md index b9725af66f080..cc30aa8752605 100644 --- a/docs/reference-guides/README.md +++ b/docs/reference-guides/README.md @@ -39,7 +39,8 @@ ## [Theme.json Reference](/docs/reference-guides/theme-json-reference/README.md) -- [Version 2 (living reference)](/docs/reference-guides/theme-json-reference/theme-json-living.md) +- [Version 3 (latest)](/docs/reference-guides/theme-json-reference/theme-json-living.md) +- [Version 2](/docs/reference-guides/theme-json-reference/theme-json-v2.md) - [Version 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) - [Migrating to Newer Versions](/docs/reference-guides/theme-json-reference/theme-json-migrations.md) diff --git a/docs/reference-guides/theme-json-reference/README.md b/docs/reference-guides/theme-json-reference/README.md index 11605b21625ad..9f53a09a97e66 100644 --- a/docs/reference-guides/theme-json-reference/README.md +++ b/docs/reference-guides/theme-json-reference/README.md @@ -2,9 +2,10 @@ 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. -- [Version 2 (living reference)](/docs/reference-guides/theme-json-reference/theme-json-living.md) +- [Version 3 (latest)](/docs/reference-guides/theme-json-reference/theme-json-living.md) ## Older versions - [Migrating to Newer Theme.json Versions](/docs/reference-guides/theme-json-reference/theme-json-migrations.md) - [Version 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) +- [Version 2](/docs/reference-guides/theme-json-reference/theme-json-v2.md) From 0d2e97ee41f8a12c5d41a938403c158cd55d79b7 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:14:39 -0500 Subject: [PATCH 12/22] Fix typo in v3 migration --- .../theme-json-reference/theme-json-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-migrations.md b/docs/reference-guides/theme-json-reference/theme-json-migrations.md index 07acf41bf2eb7..e24cf2d4213c8 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-migrations.md +++ b/docs/reference-guides/theme-json-reference/theme-json-migrations.md @@ -68,7 +68,7 @@ The default font sizes provided by core (`settings.typography.fontSizes`) have b Upgrading to v3 adjusts preset defaults to be more consistent with one another. -### How to migrate from v1 to v2: +### How to migrate from v2 to v3: 1. Update `version` to `3`. 2. Configure the changed defaults. From 8018816a21b46b8afe2a90a591afb70bfffa80e3 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:15:13 -0500 Subject: [PATCH 13/22] Fix consistency between migration docs --- .../theme-json-reference/theme-json-migrations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-migrations.md b/docs/reference-guides/theme-json-reference/theme-json-migrations.md index e24cf2d4213c8..7845c378f4a12 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-migrations.md +++ b/docs/reference-guides/theme-json-reference/theme-json-migrations.md @@ -6,7 +6,7 @@ This guide documents the changes between different `theme.json` versions and how Upgrading to v2 enables some new features and adjusts the naming of some old features to be more consistent with one another. -How to migrate from v1 to v2: +### How to migrate from v1 to v2: 1. Update `version` to `2`. 2. Rename the properties that were updated (see below) if you're using them. @@ -71,7 +71,7 @@ Upgrading to v3 adjusts preset defaults to be more consistent with one another. ### How to migrate from v2 to v3: 1. Update `version` to `3`. -2. Configure the changed defaults. +2. Configure the changed defaults (see below). ### Changed defaults From de34777f6bbbc92f33057fc05447bd5dc11d52b1 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:16:24 -0500 Subject: [PATCH 14/22] Remove reference to theme.json version in global-settings-and-styles --- docs/how-to-guides/themes/global-settings-and-styles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md index 4667e89347658..712663285486a 100644 --- a/docs/how-to-guides/themes/global-settings-and-styles.md +++ b/docs/how-to-guides/themes/global-settings-and-styles.md @@ -1,6 +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. 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. +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. ## Rationale From be4b715eee579b9c9a98f0c2de0baf570a2e2754 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:17:10 -0500 Subject: [PATCH 15/22] Add additional details for v3 migration --- .../theme-json-reference/theme-json-migrations.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-migrations.md b/docs/reference-guides/theme-json-reference/theme-json-migrations.md index 7845c378f4a12..144fd0ae1fc00 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-migrations.md +++ b/docs/reference-guides/theme-json-reference/theme-json-migrations.md @@ -79,11 +79,17 @@ Upgrading to v3 adjusts preset defaults to be more consistent with one another. In theme.json v2, the default font sizes were only shown when theme sizes were not defined. A theme providing font sizes with the same slugs as the defaults would always override them. +The default `fontSizes` slugs are: `small`, `medium`, `large`, `x-large`, and `xx-large`. + The new `defaultFontSizes` option gives control over showing default font sizes and preventing those defaults from being overridden. - When set to `true` it will show the default font sizes and prevent them from being overridden by the theme. - When set to `false` it will hide the default font sizes and allow the theme to use the default slugs. -It is `true` by default when switching to v3. This is to be consistent with how other `default*` options work such as `settings.color.defaultPalette`. +It is `true` by default when switching to v3. This is to be consistent with how other `default*` options work such as `settings.color.defaultPalette`, but differs from the behavior in v2. + +In theme.json v2, the default font sizes were only shown when theme sizes were not defined. A theme providing font sizes with the same slugs as the defaults would always override the default ones. -To keep behavior similar to v2, set this value to `false`. +To keep behavior similar to v2 with a v3 theme.json: +* If you do not have any `fontSizes` defined, `defaultFontSizes` can be left out or set to `true`. +* If you have some `fontSizes` defined, set `defaultFontSizes` to `false`. From 2a8310b6188038e8af468246743c8d5179c30004 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:18:20 -0500 Subject: [PATCH 16/22] Update "version" property docs for clarity --- docs/how-to-guides/themes/global-settings-and-styles.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md index 712663285486a..5d6dc2928eca8 100644 --- a/docs/how-to-guides/themes/global-settings-and-styles.md +++ b/docs/how-to-guides/themes/global-settings-and-styles.md @@ -125,10 +125,13 @@ 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 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. +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. -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. +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. +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. + +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. ### Settings From bca37e1fe4cda1d0968f91c8c04740b203907c64 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:19:09 -0500 Subject: [PATCH 17/22] Clarify docs for theme.json JSON schema --- .../themes/global-settings-and-styles.md | 10 +++++-- .../theme-json-reference/theme-json-living.md | 15 +++------- .../theme-json-reference/theme-json-v1.md | 18 ++++++++++- .../theme-json-reference/theme-json-v2.md | 30 +++++++++---------- 4 files changed, 43 insertions(+), 30 deletions(-) diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md index 5d6dc2928eca8..730595df4d4be 100644 --- a/docs/how-to-guides/themes/global-settings-and-styles.md +++ b/docs/how-to-guides/themes/global-settings-and-styles.md @@ -1161,9 +1161,15 @@ Within this field themes can list patterns to register from [Pattern Directory]( ## Developing with theme.json -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 +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. -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. +Many code editors support JSON schema and can provide help like tooltips, autocomplete, or schema validation right in your editor. + +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. + +The latest schema including all the latest changes from the Gutenberg plugin is available at `https://schemas.wp.org/trunk/theme.json`. + +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. ![Example using validation with schema](https://developer.wordpress.org/files/2021/11/theme-json-schema-updated.gif) diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index e9902267a2e7f..8d746df9a0001 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-living.md +++ b/docs/reference-guides/theme-json-reference/theme-json-living.md @@ -9,20 +9,13 @@ 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 guidance on how to use the `theme.json` file in your theme. -## Schema +## JSON Schema -Remembering the `theme.json` settings and properties while you develop can be difficult, so a [JSON schema](https://schemas.wp.org/trunk/theme.json) was created to help. +This documentation was generated from the JSON schema for theme.json. -Code editors can pick up the schema and can provide helpful hints and suggestions such as 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 together with a `version` corresponding to the version you wish to use, e.g.: - -``` -{ - "$schema": "https://schemas.wp.org/trunk/theme.json", - "version": 3, - ... -} -``` +The latest schema for version 3 including all the latest changes from the Gutenberg plugin is available at `https://schemas.wp.org/trunk/theme.json`. +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. ## Settings diff --git a/docs/reference-guides/theme-json-reference/theme-json-v1.md b/docs/reference-guides/theme-json-reference/theme-json-v1.md index 3e7096ee420ef..953381789de75 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-v1.md +++ b/docs/reference-guides/theme-json-reference/theme-json-v1.md @@ -1,6 +1,22 @@ # Theme.json Version 1 Reference -Theme.json version 2 has been released, see the [theme.json migration guide](/docs/reference-guides/theme-json-reference/theme-json-migrations.md#migrating-from-v1-to-v2) for updating to the latest version. +> This is the specification for **version 1** of `theme.json`. This version works with WordPress 5.8 or later. + +
+ +Theme.json version 2 has been released with WordPress 5.9. WordPress will continue to support theme.json version 1. However new features will only be added to [new versions](/docs/reference-guides/theme-json-reference/theme-json-living.md). + +When you are ready to upgrade, see the [theme.json migration guide](/docs/reference-guides/theme-json-reference/theme-json-migrations.md#migrating-from-v1-to-v2) for details on updating to the latest version. + +
+ +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 guidance on how to use the `theme.json` file in your theme. + +## JSON Schema + +The last schema for version 1 is available at `https://schemas.wp.org/wp/5.8/theme.json`. + +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. ## Settings diff --git a/docs/reference-guides/theme-json-reference/theme-json-v2.md b/docs/reference-guides/theme-json-reference/theme-json-v2.md index d30be1aa5107c..7502b85492157 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-v2.md +++ b/docs/reference-guides/theme-json-reference/theme-json-v2.md @@ -1,26 +1,24 @@ -# Theme.json Version 2 +# Theme.json Version 2 Reference -> This is the living specification for **version 2** of `theme.json`. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin. -> -> There are some related documents that you may be interested in: -> - the [theme.json v1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) specification, and -> - the [reference to migrate from theme.json v1 to v2](/docs/reference-guides/theme-json-reference/theme-json-migrations.md). +> This is the specification for **version 2** of `theme.json`. This version works with WordPress 5.9 or later. + +
+ +Theme.json version 3 has been released with WordPress 6.6. WordPress will continue to support theme.json version 2. However new features will only be added to [new versions](/docs/reference-guides/theme-json-reference/theme-json-living.md). + +When you are ready to upgrade, see the [theme.json migration guide](/docs/reference-guides/theme-json-reference/theme-json-migrations.md#migrating-from-v2-to-v3) for details on updating to the latest version. + +
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 guidance on how to use the `theme.json` file in your theme. -## Schema +## JSON Schema -Remembering the `theme.json` settings and properties while you develop can be difficult, so a [JSON schema](https://schemas.wp.org/trunk/theme.json) was created to help. +This documentation was generated from the JSON schema for theme.json. -Code editors can pick up the schema and can provide helpful hints and suggestions such as 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 together with a `version` corresponding to the version you wish to use, e.g.: +The last schema for version 2 is available at `https://schemas.wp.org/wp/6.5/theme.json`. -``` -{ - "$schema": "https://schemas.wp.org/trunk/theme.json", - "version": 2, - ... -} -``` +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.9 is available at `https://schemas.wp.org/wp/5.9/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. ## Settings From e07e861c2b2206afa29e2f2d635f69e72ac41f65 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:27:42 -0500 Subject: [PATCH 18/22] Add links to Developing with theme.json in references --- .../theme-json-reference/theme-json-living.md | 4 +++- docs/reference-guides/theme-json-reference/theme-json-v1.md | 4 +++- docs/reference-guides/theme-json-reference/theme-json-v2.md | 4 +++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index 8d746df9a0001..83b4193fc1b1c 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-living.md +++ b/docs/reference-guides/theme-json-reference/theme-json-living.md @@ -15,7 +15,9 @@ This documentation was generated from the JSON schema for theme.json. The latest schema for version 3 including all the latest changes from the Gutenberg plugin is available at `https://schemas.wp.org/trunk/theme.json`. -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. +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`. + +See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson) for how to use the JSON schema in your editor. ## Settings diff --git a/docs/reference-guides/theme-json-reference/theme-json-v1.md b/docs/reference-guides/theme-json-reference/theme-json-v1.md index 953381789de75..d7c98961b053a 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-v1.md +++ b/docs/reference-guides/theme-json-reference/theme-json-v1.md @@ -16,7 +16,9 @@ This reference guide lists the settings and style properties defined in the `the The last schema for version 1 is available at `https://schemas.wp.org/wp/5.8/theme.json`. -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. +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`. + +See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson) for how to use the JSON schema in your editor. ## Settings diff --git a/docs/reference-guides/theme-json-reference/theme-json-v2.md b/docs/reference-guides/theme-json-reference/theme-json-v2.md index 7502b85492157..a1f44a3bdb554 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-v2.md +++ b/docs/reference-guides/theme-json-reference/theme-json-v2.md @@ -18,7 +18,9 @@ This documentation was generated from the JSON schema for theme.json. The last schema for version 2 is available at `https://schemas.wp.org/wp/6.5/theme.json`. -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.9 is available at `https://schemas.wp.org/wp/5.9/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. +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.9 is available at `https://schemas.wp.org/wp/5.9/theme.json`. + +See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson) for how to use the JSON schema in your editor. ## Settings From 28d3a59f7867090befa97c75aa88ac6ee6a3f7ad Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:56:11 -0500 Subject: [PATCH 19/22] Update migrations title --- .../theme-json-reference/theme-json-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-migrations.md b/docs/reference-guides/theme-json-reference/theme-json-migrations.md index 144fd0ae1fc00..c304bfe39493e 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-migrations.md +++ b/docs/reference-guides/theme-json-reference/theme-json-migrations.md @@ -1,4 +1,4 @@ -# Migrating to Newer Versions +# Migrating Theme.json to Newer Versions This guide documents the changes between different `theme.json` versions and how to upgrade. Using older versions will continue to be supported. Upgrading is recommended because new development will continue in the newer versions. From 8487d52f6a62628994ec6b6da6081593033e984a Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 29 Apr 2024 18:56:23 -0500 Subject: [PATCH 20/22] Fix manifest order --- docs/manifest.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 2780552ebc419..05f1f36ce7ca6 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -587,18 +587,18 @@ "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-living.md", "parent": "theme-json-reference" }, - { - "title": "Theme.json Version 2 Reference", - "slug": "theme-json-v2", - "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v2.md", - "parent": "theme-json-reference" - }, { "title": "Theme.json Version 1 Reference", "slug": "theme-json-v1", "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v1.md", "parent": "theme-json-reference" }, + { + "title": "Theme.json Version 2 Reference", + "slug": "theme-json-v2", + "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v2.md", + "parent": "theme-json-reference" + }, { "title": "Migrating Theme.json to Newer Versions", "slug": "theme-json-migrations", From b858a80444cae4557abe2f2415a96b6d2a582e31 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Tue, 30 Apr 2024 11:57:51 -0500 Subject: [PATCH 21/22] Add note about gutenberg plugin --- docs/reference-guides/theme-json-reference/theme-json-living.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index 83b4193fc1b1c..0c852324ba59d 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-living.md +++ b/docs/reference-guides/theme-json-reference/theme-json-living.md @@ -1,6 +1,6 @@ # Theme.json Version 3 Reference (latest) -> This is the living specification for **version 3** of `theme.json`. This version works with WordPress 6.6 or later. +> This is the living specification for **version 3** of `theme.json`. This version works with WordPress 6.6 or later, and the latest Gutenberg plugin. > > There are some related documents that you may be interested in: > - the [theme.json v1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) specification, From c2c817cdb3f0b55fa11907f809eb15b8a3cf2113 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Tue, 30 Apr 2024 12:11:56 -0500 Subject: [PATCH 22/22] Add backgroundSize back to v2 --- docs/reference-guides/theme-json-reference/theme-json-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/theme-json-reference/theme-json-v2.md b/docs/reference-guides/theme-json-reference/theme-json-v2.md index a1f44a3bdb554..6c6e3b2894833 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-v2.md +++ b/docs/reference-guides/theme-json-reference/theme-json-v2.md @@ -28,7 +28,7 @@ See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and- Setting that enables the following UI tools: -- background: backgroundImage +- background: backgroundImage, backgroundSize - border: color, radius, style, width - color: link - dimensions: aspectRatio, minHeight