Online Workshop - Diving into theme.json

[jonathanbossenger]

Event Details

• Title: A Diving into theme.json
• Description: One of the more exciting additions to WordPress theme development that block themes make possible is the inclusion of the theme.json file. This file allows the theme developer to enable and configure everything from CSS presets to custom fonts, and more. In this session, we'll be taking a dive into the theme.json file for the new twentytwentythree default WordPress theme, to understand how it works, and what's possible.
• Target Audience: Intermediate/Advanced theme developers
• Other info:

Online Workshop Checklist:

• Create Online Workshop event on Learn WordPress Online Workshops
• Add Online Workshop to Online Workshop calendar
• Assign Co-host to event (Remove the "Needs Co-host" tag from issue once assigned)
• Hold Online Workshop
• Complete After an Online Workshop next steps
• Add link to slides and/or WordPress.tv video to GitHub issue

[jonathanbossenger]

@rosswintle has kindly offered to co-host this session.

https://www.meetup.com/learn-wordpress-online-workshops/events/288023942/

[jonathanbossenger]

Live stream of my attempts to understand what various settings do:

https://www.twitch.tv/videos/1576834601

Questions that came out of this session:

• How to enable the alignwide support correctly, and what blocks support it?
• Where is the default font set?
• Do I need to register custom templates or template parts in theme.json?
• Settings -> spacing -> spacingScale, what does that do?
• Is it possible to enable the Typography's Appearance, Letter Case, Letter Spacing, and Drop Cap settings, so they're always enabled in the Settings sidebar for a block?
• What are the best pieces of documentation you use to learn about theme.json?

[colorful-tones]

How to enable the alignwide support correctly, and what blocks support it?

This is a huge pain-point and your struggle is real.

add_theme_support( 'align-wide' ) is not needed in a block theme with theme.json. The settings.layout.wideSize and the settings.layout.contentSize is the correct way to handle wide and content width. However, I believe the way content and wide behave and surface in UI has recently been worked on in Gutenberg.

So, there are a few things to note:

1. Your first attempt failed using the index.html template and was caused by the fact that the Create Block Theme creates templates/index.html with the following: <!-- wp:query {"tagName":"main","layout":{"inherit":true}} -->. If you remove the "layout":{"inherit":true}. This setting correlates with this in the UI

So, if the "Inner blocks use full width" is enabled then alignwide and alignfull will be turned off for all nested blocks. I believe this setting is assigned to Group and Row blocks, but only 60% certain on that.

I hope that makes sense, but reading it back it seems as clear as mud. 🤦

Addendum: I know you indicated that you did not have Gutenberg activated. The UI screenshot I posted is relying upon changes in recent Gutenberg. Therefore, I would encourage you to have it activated.

[colorful-tones]

Where is the default font set?

This would be somewhere in WordPress core.

        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif",
                    "name": "System Font",
                    "slug": "system-font"
                }
           ]
        }

This entry 👆 in your theme.json is merely registering a new font family that will be surfaced in the Font Family picker in site editor/block editor. This allows the user to pick it and set if for a variety of things.

If you wanted to tell your current theme to use that specific font family then you would likely want to take the code above one step further with this:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
        "styles": {
		"typography": {
			"fontFamily": "var(--wp--preset--font-family--system-font)"
		}
        }
}

That entry is assigning the "slug": "system-font" font family to the <body> element. This is the early stages of the Webfonts API and may likely change.

If you're curious about how you might register and use a custom font (locally hosted) then here is a great overview: Self-Hosting Google Fonts in a Block Theme

[colorful-tones]

Do I need to register custom templates or template parts in theme.json?

This I have little experience with and will allow others more knowledgeable chip in.

Settings -> spacing -> spacingScale, what does that do?

This is a new addition and would require Gutenberg plugin to be activated. I have not experimented with this new addition yet. Again, I allow somebody more knowledgeable to chip in.

Is it possible to enable the Typography's Appearance, Letter Case, Letter Spacing, and Drop Cap settings, so they're always enabled in the Settings sidebar for a block?

This is something that is currently ongoing in Gutenberg and there is even a push for the upcoming 6.1 release to have more consistency. This is the larger Issue that addresses it, but Typography is here: WordPress/gutenberg#43242

[colorful-tones]

What are the best pieces of documentation you use to learn about theme.json?

Another huge pain point. I would say: experiment with theme.json and the schema documentation are the best documentation at the moment. I learned by trial and error and creating Extendable theme with the dozen style variations within.

[pbking]

Do I need to register custom templates or template parts in theme.json?

Yes (unless things have changed. :P ). See blockbase's theme.json file as an example. https://github.com/Automattic/themes/blob/trunk/blockbase/theme.json

Registering them thus allows users to select them as the templates for page/post or swap out template parts into the correct space (headers for headers, etc)

[jonathanbossenger]

Thank you @colorful-tones and @pbking for all this insight.

[jonathanbossenger]

Another huge pain point. I would say: experiment with theme.json and the schema documentation are the best documentation at the moment. I learned by trial and error and creating Extendable theme with the dozen style variations within.

I think as I work through this course, I'm going to see if I can add some more context/examples to the version 2 living document.

[colorful-tones]

That doc is new to me and thanks for sharing!

[jonathanbossenger]

Slides created for the Workshop

https://docs.google.com/presentation/d/1-ek6T5EpZfwDve1_wjFQnMKUHCgwmUp0h4Y7qDPtkEA/edit?usp=sharing

[glendaviesnz]

Settings -> spacing -> spacingScale, what does that do?

@jonathanbossenger FYI I added some docs for this here

[jonathanbossenger]

Awesome, thank you @glendaviesnz

I plan to review these new 6.1 features when they're merged into core.

[jonathanbossenger]

• WP TV Video - https://wordpress.tv/2022/09/02/lets-code-diving-into-theme-json/
• Slides - https://www.slideshare.net/psykro/lets-code-diving-into-themejson