search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.32k stars 4.12k forks source link

Keep "theme.json" properties documentation properly updated in the handbooks while avoid duplicate themes content in Block Editor Handbook and Theme Handbook #56499

Open juanmaguitar opened 9 months ago

juanmaguitar commented 9 months ago

Shape the section Block Editor Handbook / Reference Guides / Theme.json Reference to take into account the new Global Settings and Styles (theme.json) available from the Theme Handbook.

The purpose of this work is to avoid duplication of information and provide the required cross-sites references (Block Editor Handbook <> Themes Handbook)

Some ideas related to this work provided by @justintadlock

At the very least, there should be a link to the Global Setting and Styles chapter. If you wanted to go the extra mile, the Living Reference page could link to individual docs. For example, the Settings section could link to the Settings doc, the appearanceTools section could link to the Appearance Tools doc, and so on.

Some flags related to this work raised by @bph

what to do about duplicate themes content in both handbooks? The trigger for the question was this PR Add backgroundImage to the theme json docs for appearanceTools #55376 which updated this page https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/ but not this page: https://developer.wordpress.org/themes/global-settings-and-styles/settings/appearance-tools/

jhmonroe commented 1 month ago

Hey @juanmaguitar @justintadlock ! So thankful I found your issue while trying to figure out why I couldn't find some things in the main/latest theme.json reference. Agreed that there is too much content spread across too many locations, to the point of being very difficult to find (or you start doubting yourself that an option ever existed in your memory, ha!). It's a bit confusing to know when a developer is supposed to refer to the Block Editor Handbook vs the Theme Handbook:

EXAMPLE:

LOCATION 1 & THE ISSUE:

BLOCK EDITOR HANDBOOK > REFERENCES GUIDES > THEME.JSON REFERENCE > Theme.json Version 3 Reference (latest) https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/ elements & blocks are not mentioned at all in the tables as being supported inside STYLES or SETTINGS

BLOCK EDITOR HANDBOOK > REFERENCES GUIDES > THEME.JSON REFERENCE > AVAILABLE STYLES OPTIONS https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/styles-versions/ elements and blocks not mentioned

(Aside: blocks are mentioned here and the way they should be notated in Theme.json (ie: core/block-name) and a great place to see Attributes available to it, but not in a table as in Styles Options and not in the context of where they can be used in theme.json: https://developer.wordpress.org/block-editor/reference-guides/core-blocks/)

Schema: https://raw.githubusercontent.com/WordPress/gutenberg/trunk/schemas/json/theme.json elements & blocks are not listed as possible children of STYLES or SETTINGS inside the schema (which is perhaps why the reference makes no mention of them) and why coders will not have these available as autocompletes inside VSCode etc.

LOCATION 2:

elements and blocks are mentioned if you drill down into these sections

THEME HANDBOOK > GLOBAL SETTINGS AND STYLES (theme.json) > SETTINGS SETTINGS: https://developer.wordpress.org/themes/global-settings-and-styles/settings/

THEME HANDBOOK > GLOBAL SETTINGS AND STYLES (theme.json) > SETTINGS > BLOCKS https://developer.wordpress.org/themes/global-settings-and-styles/settings/blocks/

THEME HANDBOOK > GLOBAL SETTINGS AND STYLES (theme.json) > STYLES STYLES: https://developer.wordpress.org/themes/global-settings-and-styles/styles/

THEME HANDBOOK > GLOBAL SETTINGS AND STYLES (theme.json) > STYLES > APPLYING STYLES https://developer.wordpress.org/themes/global-settings-and-styles/styles/applying-styles/

not mentioned here:

THEME HANDBOOK > GLOBAL SETTINGS AND STYLES (theme.json) > STYLES > SETTINGS REFERENCE https://developer.wordpress.org/themes/global-settings-and-styles/settings/settings-reference/

THEME HANDBOOK > GLOBAL SETTINGS AND STYLES (theme.json) > STYLES > STYLE REFERENCE https://developer.wordpress.org/themes/global-settings-and-styles/styles/styles-reference/

LOCATION 3:

BLOCK EDITOR HANDBOOK > HOW-TO-GUIDES > THEMES > GLOBAL SETTINGS & STYLES (theme.json) elements & blocks are listed in the Block Editor How-To Guide for Global Settings & Styles here: https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/ (this page is really the easiest cheat-sheet for quickly seeing/copying all the available values)

CONCLUSION

We should mention elements and blocks in the Block Editor handbook (if this is the preferred way of the future), Theme.json reference, and Schema if they are available and referenced elsewhere.

Otherwise I imagine others will, as I do, find themselves having all of these tabs open plus @carolinan wonderful page to cross-reference: https://fullsiteediting.com/lessons/creating-theme-json/ (mentions elements)

Mentions setting & styling blocks in theme.json: https://fullsiteediting.com/lessons/global-styles/

Here she even lists ALL the elements available inside theme.json: https://fullsiteediting.com/lessons/theme-json-elements/