Document and clarify theme.json with a full example for latest WP releases #42690
Description
What problem does this address?
My experience of last half year is that it is generally difficult to keep up with all the settings that are introduced with theme.json in each patch. What is working? What is not? "Do I add an empty array to remove this? "Oh here it is a true/false instead."
I've seen quite a few issues where in the comments is said: "this doesnt work yet". But how do we developers know?
These are our current sources:
https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/ (outdated, 5.9)
https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/ (outdated, 5.8)
What is sorely missing in documentation is one complete overview of ALL the possible settings and styles, that is up to date with latest releases of WordPress.
Arguments:
- We currently have examples for many settings and their values (Typography, spacing, etc.). But no where is specified for which blocks it works and for which blocks it doesnt work.
- In the handbook: https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#settings-can-be-controlled-per-block. It is stated that "For more granularity, these settings also work at the block level in theme.json." This statement creates a false expectation of how theme.json currently works (yes for some blocks, no for others).
- For example a setting like BlockGap is not accessible for each block (i.e. query/post-template), but where is this documented?
- Some controls are turned on by default, others are not. How do we change this (why is image-size on a feat. image only accessible by the plus icon, and how can we put it up front as default behavior?
What is your proposed solution?
Let's clear up all this ambiguity on one of the most important settings file in FSE wordpress.
Add a complete list of all the possible settings & styles that "are working" for WordPress 6.0 to (bottom of) the Handbook chapter about theme.json (or update the living reference).
Where:
- For each setting per block, the possible values are defined and documented "what they do".
- Explain what cascades and what not (general settings -> block level settings).
- Which "elements" are accessible for which blocks?
- Remove 'appearanceTools' settings asap, because it is really confusing and muddying the waters for theme.json clarity.