Update documentation for theme.json version 3

[ajlende]

Dev Note 📝

See #58409 (comment)

What?

Updates documentation around theme.json version 3.

Why?

Follow-up to #58409 to better document theme.json version 3.

How?

• Fixes the menu (docs/manifest.json) and TOC (docs/toc.json).
• Fixes hand-written TOC in reference-guides.
• Fixes typo in migrations heading.
• Fixes incorrect wp version in v3 reference.
• Clarifies the migration process even more.
• Updates documentation to hopefully help with some confusion on backwards compatibility.
  • Updates description for the version property in global-settings-and-styles.md
  • Adds notices for backwards compatibility in all theme.json version references.
• Updates references to theme.json "version": 3 in docs.
• Remove changes from v2 docs since wp 6.5 release to be consistent with what would appear in the JSON schema file.
• Other assorted fixes to related documentation in files that I was working in.

Testing Instructions

Proofread docs and check for working links.

Testing Instructions for Keyboard

Screenshots or screencast

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ajlende <ajlende@git.wordpress.org>
Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>
Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>
Co-authored-by: oandregal <oandregal@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[fabiankaegy]

Why is this here removed? That option was introduced in 6.5 and therefore exists in version 2

[ajlende]

Thanks for flagging 🙂

I just removed everything I found in the diff from wp/6.5...HEAD.

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 c58b8b3239..0c852324ba 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -31,9 +27,9 @@ Code editors can pick up the schema and can provide helpful hints and suggestion
 
 Setting that enables the following UI tools:
 
-- background: backgroundImage
+- background: backgroundImage, backgroundSize
 - border: color, radius, style, width
-- color: link
+- color: link, heading, button, caption
 - dimensions: aspectRatio, minHeight
 - position: sticky
 - spacing: blockGap, margin, padding
@@ -97,6 +93,7 @@ Settings related to colors.
 | text | boolean | true |  |
 | heading | boolean | true |  |
 | button | boolean | true |  |
+| caption | boolean | true |  |
 
 ---
 
@@ -107,6 +104,7 @@ Settings related to background.
 | Property  | Type   | Default | Props  |
 | ---    | ---    | ---    |---   |
 | backgroundImage | boolean | false |  |
+| backgroundSize | boolean | false |  |
 
 ---
 
@@ -161,7 +159,7 @@ Settings related to spacing.
 
 | Property  | Type   | Default | Props  |
 | ---    | ---    | ---    |---   |
-| blockGap | undefined | null |  |
+| blockGap | boolean, null | null |   |
 | margin | boolean | false |  |
 | padding | boolean | false |  |
 | units | array | px,em,rem,vh,vw,% |  |
@@ -177,12 +175,14 @@ Settings related to typography.
 
 | Property  | Type   | Default | Props  |
 | ---    | ---    | ---    |---   |
+| defaultFontSizes | boolean | true |  |
 | customFontSize | boolean | true |  |
 | fontStyle | boolean | true |  |
 | fontWeight | boolean | true |  |
-| fluid | undefined | false |  |
+| 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 |  |
@@ -266,6 +266,7 @@ Typography styles.
 | fontWeight | string, object |  |
 | letterSpacing | string, object |  |
 | lineHeight | string, object |  |
+| textAlign | string |  |
 | textColumns | string |  |
 | textDecoration | string, object |  |
 | writingMode | string, object |  |

If backgroundSize was added in 6.5, the schema and docs must have been updated after the release and must not have been backported to the wp/6.5 branch.

[ajlende]

Opened #61264 for those backports to 6.5 to fix up the schemas for that version.

[fabiankaegy]

Left one comment that I think requires a change. But besides that the updates look great 👍

[juanmaguitar]

@ajlende, is there any communication to the community (#dev-notes, #gutenberg-new, ...), announcing this update of theme.json from v2 to v3 and providing some context about this update?

As per #40232 (led by @oandregal), it seems this update was made some time ago.

There was a post explaining the update to v2 of theme.json (Updates for Settings, Styles, and theme.json) but I haven't found any for the migration to v3

I think it would be useful for developers to have a link from the docs to such a post in the same way there is one for v2 at Block Editor Handbook > Reference Guides > Theme.json Reference > Migrating to Newer Versions

Refer to the dev note for the release and the reference documents for the respective v1 and v2 versions.

[oandregal]

As per #40232 (led by @oandregal), it seems this update was made some time ago.

That PR was closed and not merged. The one that updated the version is #58409 as far as I'm aware, which is a change that will land in 6.6.

[juanmaguitar]

That PR was closed and not merged.

@oandregal You're right 🤦‍♂️ Thanks for the clarification

The one that updated the version is #58409 as far as I'm aware, which is a change that will land in 6.6.

@ajlende I see now there's a DevNote in progress

[ajlende]

Looks like things aren't rendering properly on the website. I'll be adding another follow-up to fix that until whatever markdown parser is being used for wordpress.org gets fixed.

Is there a good way to preview this? Because it renders just fine in GitHub and my local markdown previewer.