WordPress contributors have updated the Theme Handbook to include a new chapter on block templating. The chapter covers how the WordPress block template system works, how to build custom templates and parts and include them in a theme. This is critical documentation designed to provide a learning path for those who are building their first block themes.

Automattic-sponsored developer advocate Justin Tadlock announced the update on Twitter, noting that it also includes a couple of new docs in the Global Settings and Styles chapter for registering template-related features in theme.json, and the same for template parts.

The new chapter on block templating is just one part of a larger effort to overhaul the Theme Handbook for modern day WordPress. Contributors are transitioning the focus from classic theming to block theming, with just one chapter in the handbook devoted to classic themes.

“It was created during a time when classic themes were the only method of front-end design for WordPress,” Tadlock said in the proposal to overhaul the handbook. “Much of its content now exists in a transitory state between classic and modern block theming. This has created a scenario where the handbook sometimes reads more like patchwork than if it were built with a single vision. That is often a natural result of adding new documentation over years.”

The proposal does not recommend scrapping all of the existing content but rather carrying some of it forward to be updated and reorganized. A good portion of the existing content is still relevant to be migrated to the Classic Themes chapter.

Overhauling the Theme Handbook is a colossal effort that’s still ongoing. It’s being managed under a tracking ticket on GitHub. The new chapter better supports developers who are just figuring out how the WordPress block template system works, but there are many more chapters that need attention. Anyone who would like to get involved in the project can select any issue on the ticket to get started.