Update theme schema docs #43716
Update theme schema docs #43716
Conversation
DaisyOlsen
requested review from
ajitbohra,
ajlende,
fabiankaegy,
juanmaguitar,
nerrad,
ntwb and
ryanwelcher
as code owners
|
Hi, thanks for contributing to the docs! We had an in-depth discussion about adding
Our workaround was adding a separate page for the older versions with renamed properties and a migration guide in #37886. Maybe it could be helpful to surface those additional docs in the latest generated page? |
|
The older versions pages is useful when the theme.json version changes, but not as helpful for example for WordPress 6.1 (and all the Gutenberg versions), where it was decided to not increase the theme.json version. |
|
I would still, very much, like to find a path forward for adding this, and potentially other, helpful information into the living references. I've learning more about the JSON Schema draft-04 spec and looking for possible solutions. Is it possible that the current automation is not the best way to maintain the reference doc to the level of detail that it really needs? |
We do have different versions of the schema for each WordPress version starting with 5.8 at https://schemas.wp.org/wp/5.8/theme.json, for example. Those are useful in editors, but maybe we could leverage them for generating documentation too. The URL just redirects to the schema on the GitHub branch for the WordPress version. |
|
I think that having a "diff" between the WordPress versions would help, because it would make it much easier to see what actually changed. |
That could be an interesting avenue to explore. I wonder, though, if the effort of improving the reference through automation is the most efficient path forward. This specific item feels like just a single example of the shortcomings of automating the reference based on the schema. |
|
I think I'm going to approach what I was trying to accomplish in another way :-) Thanks for the feedback! |
3 participants
What?
This PR introduces a new column to the Settings Properties tables for the living theme.json reference that indicates the WordPress version in which the property was introduced.
Worth Noting
WordPress 5.8 shipped with some properties that were renamed in 5.9. The since values here indicate 5.9 as the since version for those items. That seemed the best solution to me but i'm open to ideas. The areas that are currently expected to land in 6.1 are indicated with that version in the schema. This is also open for discussion. Should anything be rolled back this will need to be adjusted. One possible alternative would be to include the plugin version until code has been merged into core and released. That would require a manual review which might not be the worst thing ever.
Why?
It can be difficult to determine what options are new in the reference documentation. This will make the information about when an option was added to core easily added in a persistently available way with minimal need for maintenance beyond what is already necessary to keep the reference document up to date.
How?
Added a "since' key to the theme.json schema file for each of the properties that have a table on the living reference doc. Also added the table column to the docs generator to accommodate the new information.
Testing Instructions
schemas/json/theme.jsonnpm run docs:build/docs/reference-guides/theme-json-reference/theme-json-living.mdScreenshots or screencast