New Pages for the Block themes

[TeBenachi]

As we are moving forward with merging with the Theme handbook, here is a list of suggested new pages related to the block theme. The new pages will go under the Block theme section.

==

Introduction and overview Difference between block theme and classic theme

How to create a block theme

• File structure
• Templates
• Parts
• Ways to create the templates (Manually, Site Editor, Template Editing mode)
• Exporting
• Additional templates

Global Styles and Theme.json Theme Support

Converting classic theme to block theme (#106)

• Benefits of changing from theme to block theme
• Converting customizer into blocks
• Using global styles
• Examples (Site logo, Colors or widgets) including snippets and code
• Theme before and after
• Links and resources

What is patterns? How to make patterns? What are the patterns category?

[carolinan]

In addition to the above, we need to include information about block markup and how to use it.

Please consider the following updates to be a starting point. Feel free to edit/remove/add content, including moving it to different documents

There is a scheduled update for the entry page for block themes that is ready to be reviewed. I listed the theme basics chapter as a prerequisite so that we do not need to bring up details about functions.php, style.css, etc a second time. https://developer.wordpress.org/wp-admin/post.php?post=138837&action=edit

I created a new one-page draft that so far includes:

• File structure
• How to create templates in the site editor,
• What a template part is, How to create template parts manually, how to create template parts in the site editor, how to include the template part in a template, how to add the template part to theme.json, and why.
• Exporting.

I left the "creating templates in the template editor section" as a link to the existing support article. This is not intended to be published as-is, but to be moved to new pages if we decided it needs to be separate pages and not just sections. https://developer.wordpress.org/wp-admin/post.php?post=138840&action=edit

[carolinan]

Theme.json can be used by both classic themes and block themes. The existing page is in the advanced section, and has a scheduled update that is ready for review: https://developer.wordpress.org/wp-admin/post.php?post=138713&action=edit

[TeBenachi]

Thank you for the write-up! Thank you.

One thing I thought we could add is about the reference under Exporting.

When an exported file includes the reference number (e.g. “ref:123”), it causes an error when using the file on another site. It took me a while to figure this out. It might help others to clarify.

Something like….

If an exported file includes a reference number to a specific block such as navigation, the reference number should be removed.

<!-- wp:navigation {"ref”:123} /—>

Should be

<!-- wp:navigation /-->

I also thought about the prefix (different from classic themes) and translation, but the “Converting classic theme to block theme” section might be appropriate.

[carolinan]

Added a section about enqueueing block styles, but it is very long. Eventually, this may be replaced by a proper developer reference page for the new wp_enqueue_block_style().

[carolinan]

Added a theme.json setting and add_theme_support comparison table.

[carolinan]

Theme authors are asking how to correctly load JavaScript in the different editors. I think we need to include that, but I don't actually have the answer. (My personal preference is don't do that, and rely on blocks instead)

[TeBenachi]

Thank you so much for updating. Looks really great. Amazing! https://developer.wordpress.org/wp-admin/post.php?post=138840&action=edit

I realized I forgot to include the How to create a child theme section in the above list. Is it Ok if I add #105, perhaps after the exporting?

For Javascript, can we refer authors to Loading JavaScript page?

[carolinan]

Yes, we can refer to the Loading JavaScript page in the block editor handbook. I was hesitant to recommend enqueue_block_editor_assets because it used to trigger a warning. The warning has now been removed.

[carolinan]

The original page I started writing in is now called "Block theme setup" This page has been published. Please feel free to continue editing.

I moved the template/parts and block markup content to a new page called "Templates and template parts" This page has been published

[github-actions[bot]]

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

[carolinan]

Most of these pages have already been added; the ones I am unsure of is:

1. Examples (Site logo, Colors or widgets), including snippets and code
2. Theme before and after

I am not sure what 1 refers to. I think 2 might be the comparison table? https://developer.wordpress.org/themes/block-themes/#differences-and-similarities-between-classic-themes-and-block-themes