10up has published a Gutenberg Best Practices website as a public resource with tutorials, documentation, and example code. Maintaining current documentation has not been a strong point of the official Gutenberg project as the pace of the project makes it difficult for contributors and extenders to keep up.
“Gutenberg introduced an entirely new editorial paradigm for content creation and page building within WordPress,” 10up Associate Director of Editorial Engineering Fabian Kaegy said. “Because the block editor is still fairly new, it is advancing quickly and changes are introduced regularly; as such, learning opportunities are scarce and we have felt an absence of best practice documentation that meets 10up standards for craftsmanship.”
10up’s Gutenberg Best Practices were written to supplement WordPress’ core documentation with what Kaegy said is a “more client-services-centric approach tailored to engineering enterprise-level editorial experiences.”
For developers who are brand new to working with the block editor, the Reference section has a wealth of information about the anatomy of a block, the fundamentals of block theming with theme.json, block extensions, block variations, and more, with supporting videos and gifs. The documentation also gives a little more context for practical usage. For example, the section about Block Transforms includes information about when and how to define block transforms.
The Training section of 10up’s Gutenberg Best Practices contains a mini crash course on the file structure of a block and all of its components, and how to build a custom block using the 10up Starter Block. This is especially helpful for developers looking for some extra guidance developing their first blocks.
The Guides section contains more advanced topics like extending core blocks and including frontend JS with a block. The documentation is available on GitHub for anyone to contribute edits. The site also links to a discussion board on GitHub where developers are welcome to join discussions and workshop the best practices in collaboration with 10up employees. 10up has published the Gutenberg Best Practices website with a beta designation and intends to update and expand it as WordPress evolves.
Kudos to the 10up team for putting this together and publishing it. When I sent it to my coworker to review he summed up the material really well: “It has a good learning journey.”
What stands out to me over other resources about blocks is the writer explains why they consider their approach the best practice, as well as the common pitfalls you might encounter. That information is invaluable when you first start developing blocks.