Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

theme.json docs: add missing settings & styles #36137

Merged
merged 2 commits into from
Nov 2, 2021
Merged

theme.json docs: add missing settings & styles #36137

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f4fc86f
Update settings
oandregal Nov 2, 2021
0fa665f
Update styles
oandregal Nov 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions docs/how-to-guides/themes/theme-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,9 @@ The settings section has the following structure:
{
"version": 1,
"settings": {
"border": {
"customRadius": false
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This landed in WordPress 5.8.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was 5.8.1 - WordPress/wordpress-develop#1513.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, thanks for catching that. I see what happened. I think it's fine to leave it in the "WordPress" as it was a bug and should have been ported to 5.8 anyway.

However, it prompts us to improve the docs to better pin a given setting/style to a given WordPress release (we'll certainly need this for WordPress 5.9).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The handbook setup is very limited, so I wonder if we should just have different subsections per release. Something along the lines of:

  • Settings
    • WordPress 5.8
    • WordPress 5.9
    • Gutenberg

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, it prompts us to improve the docs to better pin a given setting/style to a given WordPress release (we'll certainly need this for WordPress 5.9).

💯 This would be useful in docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mkaz, do you have any suggestions for this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For docs, I think we just need to use @since comments similar to how we would in code. It's not quite valid JSON, but if we consider the file to be JSONC (json with comments) we could do:

"settings": {
		"border": {
			// @since wp5.8.1
			"customRadius": false
			...

},
"color": {
"custom": true,
"customDuotone": true,
Expand Down Expand Up @@ -238,6 +241,7 @@ The settings section has the following structure:
"wideSize": "1000px"
},
"spacing": {
"blockGap": null,
"customMargin": false,
"customPadding": false,
"units": [ "px", "em", "rem", "vh", "vw" ]
Expand All @@ -246,12 +250,13 @@ The settings section has the following structure:
"customFontSize": true,
"customLineHeight": false,
"dropCap": true,
"fontFamilies": [],
"fontSizes": [],
"fontStyle": true,
"fontWeight": true,
"letteSpacing": true,
"textDecoration": true,
"textTransform": true,
"fontFamilies": [],
"fontSizes": []
"textTransform": true
},
"blocks": {
"core/paragraph": {
Expand Down Expand Up @@ -611,6 +616,9 @@ Each block declares which style properties it exposes via the [block supports me
{
"version": 1,
"styles": {
"border": {
"radius": "value"
},
"color": {
"background": "value",
"gradient": "value",
Expand All @@ -636,6 +644,7 @@ Each block declares which style properties it exposes via the [block supports me
},
"elements": {
"link": {
"border": {},
"color": {},
"spacing": {},
"typography": {}
Expand All @@ -649,6 +658,7 @@ Each block declares which style properties it exposes via the [block supports me
},
"blocks": {
"core/group": {
"border": {},
"color": {},
"spacing": {},
"typography": {},
Expand Down Expand Up @@ -685,6 +695,9 @@ Each block declares which style properties it exposes via the [block supports me
"gradient": "value",
"text": "value"
},
"filter": {
"duotone": "value"
},
"spacing": {
"blockGap": "value",
"margin": {
Expand All @@ -705,6 +718,7 @@ Each block declares which style properties it exposes via the [block supports me
"fontSize": "value",
"fontStyle": "value",
"fontWeight": "value",
"letterSpacing": "value",
"lineHeight": "value",
"textDecoration": "value",
"textTransform": "value"
Expand Down