Meeting Notes: Theme docs updates for WP 5.9 and block themes

Who: @milana_cap, @mkaz, @utz119

When: Dec 8, 2021 @ 1500 UTC


We met to discuss the upcoming blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. themes in WP 5.9 and where to document with relation to the existing Theme handbook.


Block themes has a small call out as an experimental feature now on the first page of the Theme handbook. The next step is to update that page with a clear distinction between Classic themes and Block themes, a brief explanation about the differences, and links to learn about each. Classic themes links will continue to theme handbook, Block theme links will go to Block editor handbook.


We discussed what current documentation we have between the two handbooks. The ongoing goal will be to highlight the areas of overlap between classic and block themes and keep those in the handbook, try not to duplicate any documentation in either handbook, and use plenty of cross links so developers can find what they need.

We touched on some complexities with the Block editor handbook structure. The initial goal was teaching developers about blocks, getting them started learning and creating blocks. We need to look at information architecture and flow of the handbook to better help developers navigate. For with WP 5.9 features like block themes, theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., styles and settings a developer can be greatly involved with topics covered in the handbook without having to create a block.

A larger project that needs to be tackled is the information architecture of all developer handbooks and documentation. Valuable content is being created and organized in various different areas in different ways, this makes it hard for developers to find what they need. For example, great developer content is created within Learn that is not cross-linked with The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. Additionally, browsing the “Common APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.” or “Code Reference” sections only return the PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. APIs when there is a large suite of JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. APIs in the Block editor handbook.