[Theme Handbook Overhaul] Global Settings and Styles > Settings > Settings Reference

[justintadlock]

This ticket is a part of #816 and will be used for creating new page titled "Settings Reference" under Chapter 3: Global Settings and Styles > Settings.

@tinjure20 and I have been discussing what this might look like and will begin working on a new page soon. Initial Google Doc will be added next week.

[github-actions]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[tinjure20]

@justintadlock Thanks for creating ticket as discussed. Let's work together on this ticket.

[justintadlock]

I've created a Google Doc that we can work from here: https://docs.google.com/document/d/1DeQ7iM19J8a7Zs_lAZ_HRIga5hyKOTXmhlzXZrKiVkE/edit?usp=sharing

[tinjure20]

Given that this is still a work-in-progress copy, I have added a few tables from my notes, which I'd prepared a while back. I have not had a chance to check and verify with recent updates.

[justintadlock]

After chatting with @tinjure20, we decided to split this up into two separate docs:

• Settings Reference
• Styles Reference

Given the separation of the Settings and Styles sections in the current chapter outline, this makes a lot more sense. Plus, it should be easier for readers to follow by shortening the individual docs.

I'm in the process of splitting these into two separate docs and rearranging this a bit in the tracking ticket.

[justintadlock]

I've left this ticket open and renamed it as the primary Settings Reference ticket.

For the Styles Reference doc, I've created a separate ticket: #1120

[justintadlock]

I've went through this, cleaned it up a bit (mostly narrowing it down to the necessary things), linked out to the new theme.json doc pages, etc.

It should be ready to review at this point.

[justintadlock]

This is now a draft for the Theme Handbook: https://developer.wordpress.org/wp-admin/post.php?post=149100&action=edit

[ouw-jvt]

There are a few settings that must be explicitly set values (not references or css variables) due to the way they are digested by the PHP side of things. It would be helpful to denote this in this reference, perhaps as another column. "Supports references" - something like that?

Related to these issues in the Gutenberg tracker:

• Typography: theme.json "layout" settings cannot be custom css variables or references, must be explicit values
• Fluid typography: Numerical values shall support "ref" data type for better design synchronization e.g. typography.fluid.maxViewportWidth = "ref": "settings.layout.contentSize"

[justintadlock]

I'd prefer to avoid extra table columns just based on the current handbook design (a new design is in progress). However, I think we can add a Notice block to specifically point out those for the time being since it'd be just two notes.

[ouw-jvt]

That would be excellent, thanks!

[justintadlock]

Published here: https://developer.wordpress.org/themes/global-settings-and-styles/settings/settings-reference/