Navigating the Block Editor Handbook

If you’re developing for the block editor, the Block Editor Handbook is the canonical resource. Whether you’re building a custom block for a client project, a completely original block and the plugin that implements it – perhaps with a view to uploading it to the plugin directory – or, even if you are planning to contribute to the Gutenberg project itself, you’ll find yourself turning to the Handbook again and again.

The Block Editor Handbook can feel intimidating even to a seasoned developer. If you are completely new to block development, it’s perfectly natural to feel completely overwhelmed when encountering it for the first time.

There’s a ton of content in the handbook, and there are many ways in which to approach it. If you’re trying to learn something, whether it’s the fundamentals of block development, or how to solve a particularly sticky problem, it can be difficult to know where to start or where to find the relevant information.

Hence this post which has been written to help you to orient yourself and assist you in navigating the handbook. After reading this post you will hopefully be able to find what you need just a little bit more quickly.

Let’s take a look at what will be covered in this post:

It will kick off with an overview of the structure of the handbook. This will help you to orient yourself within it.
If you’re just starting out with block development, a recommended pathway will be suggested. This will help you learn the fundamentals in a structured and progressive way.
Next up is some guidance for if you’re working on a specific block project and need to find relevant information.
There then follows a curated selection of advanced topics.
A collection of links to other resources, separate from the handbook, that you can turn to for further help is up next.
Finally, some guidance on contributing will round out the post.

1. Structural overview

The handbook follows the structure outlined in the Unified Theory of Documentation. The Unified Theory separates documentation according to its purpose, i.e. learning, problem solving, understanding, and information.

Tutorials (learning oriented) – the Getting Started section of the handbook leads you through the fundamentals of block development.
How-to’s (problem oriented) – the How-to Guides section shows you how to solve particular problems that you might run into. Plus, you’ll get example code that you can reuse.
Explanations (understanding oriented) – the Explanations section gives you the why behind the how. Here you can reinforce your practical knowledge with a theoretical understanding of how the block editor works and is structured.
Reference (information oriented) – the Reference Guides are where you can look up the details of the particular API that you need to work with.

2. Learning block development

So, you’re new to block development and need to learn some basics. You have questions – lots of questions!

Where do you start? What do you move on to next as you progress? How can you be sure you’re building on what you previously learned? In particular, how can you know that you’re not out of your depth and trying to learn something without some prerequisite knowledge already in place?

Before diving into block development there are some key things you should know and some preliminaries that you should have under your belt:

You should, of course, learn to use the block editor itself, if you haven’t already.
Also, familiarize yourself with the components of the user interface.
Read the Key Concepts page, to make sure you understand some important foundational principles needed for block development.
You should know about Data Flow and Data Format, this is essentially the lifecycle of a block.

Now you’re ready to start learning to build blocks, with some practical project-based tutorials:

You will need to set up your development environment.
Once you have a development environment you can move onto the Create a Block Tutorial which leads you through the process of building a basic static block (as opposed to a dynamic block – see below for more on dynamic blocks).
With that under your belt you can head over to the Blocks How-to Guide. That section incrementally introduces the functionality you will need when building blocks. It refers to the code in the gutenberg-examples repo, so it’s a good idea to clone that repo locally.
As you work through the Blocks How-to Guide give special attention to the page on dynamic blocks. Understand the differences between dynamic blocks and static blocks, and when to use which.
It’s common to have to use WordPress data in a block project, i.e. fetch the data, add a new entity such as a post in the database, or edit that new entity. Get some practice doing all of that with the Create your First App with Gutenberg Data tutorial.

Now that you’ve got your hands dirty with some practical projects, deepen your understanding with the following:

Become familiar with the different packages you can use and where they live. Knowing just that will save you lots of time when you’re working on a project and need quick answers from the Reference Guides section.
You’ve already covered a good part of it, so finish working through the Architecture section to make sure you have a solid theoretical grounding to underpin your development work.
The block editor is a visual medium, so you’ll want to learn the principles and best practices of Block Design. It’s not so much about making blocks look lovely (although good design does build trust in any site’s information). More important is the visual flow: how do your controls work? Are options and settings easy to find? Is it clear what they do?
Have a browse through the Glossary to make sure you understand the terminology used in the handbook.
The FAQs will hopefully answer any questions that you might still have.

3. Working with blocks

With all that learning done, you’ll be keen to dive in and start building your projects. This is when you can dig into the How-to Guides and Reference Guides sections which are there to ease the path and lighten your load.

How-to Guides

It’s impossible to anticipate every scenario and use case you might run into, but these how-to guides are the ones you are most likely to need and they can give you recipes and code samples for the tasks that you’ll use the most:

Block Controls: Block Toolbar and Settings Sidebar shows you how to add controls to the block’s interface so your users can interact with it and change settings.
Notices shows you how to use notices in the editor to draw users’ attention to important information.
How to use JavaScript with the Block Editor.
Create your First App with Gutenberg Data shows you how to work with WordPress data. It’s the same section mentioned above, but you might have skipped it earlier if you didn’t have time and didn’t need the information immediately.

Reference Guides

You will find yourself turning to the Block API Reference very frequently. Your needs will vary, but almost every block development project will involve these basics:

It’s worth noting that if you use the @wordpress/create-block tool to scaffold your block project, that tool will handle the bulk of the work with Registration and with Edit and Save. Still, it’s worth taking the time and effort to understand what the scaffolding tool has done for you.

The Core Blocks Reference is your guide to the blocks that already come with Gutenberg, and each item has a handy link to the source code in the Gutenberg repository. When you can see how the core developers have built certain block functionality, you’ll see how you can apply that knowledge when you’re building your own blocks.

Gutenberg is built with React and you will almost certainly use components in your block projects. Conveniently, Gutenberg comes with a variety of pre-built components that you can use in your projects and the Component Reference details how to use each component. You can also use the accompanying Storybook Tool to interactively experiment with components to decide which ones you want to use in your project.

The Package Reference details the packages that are available for you to use in your project. It’s impossible to anticipate every scenario you might encounter, but these are a few of the ones that you are most likely to install into your project and import from:

4. A curated selection of advanced topics

As you take on more advanced projects, you will need more advanced tools. Again, there’s no way to anticipate every single need, but some things come up more often than others. Here are a few of the things that come up most frequently that you will probably need at some point in your block development career:

5. Further resources

The handbook should be considered the canonical resource for all things related to block development. But it is not the only one, and you might find some others touch on things that are relevant to your project in the moment, or they may simply be easier to understand. Here are a few that are recommended.

Courses

There are some useful courses available on learn.wordpress.org:

Introduction to Block Development: Build your first custom block
This course is a step-by-step tutorial that gently guides you from first principles to accomplished block developer. The course will lead you by the hand as you develop an example project. It will also give you a solid foundation that will help you get the most from the handbook.
Converting a Shortcode to a Block
This course shows you how to do something that is a common use case, namely taking a legacy shortcode-based plugin and blockifying it. So common is this use case that it once (almost entirely on its own) prompted a regression in the Gutenberg plugin.
Using the WordPress Data Layer
This course teaches the principles of working with WordPress data in the block editor, though it is largely a re-working of the Create your First App with Gutenberg Data tutorial in the handbook that was mentioned earlier.

Videos

An ever-growing resource of videos ranging from talks at WordCamps to recordings of online workshops, WordPress.tv is sure to have something that will aid your learning and help you to solve your problems.

Blog

If you’re reading this you’ve already found the WordPress Developer Blog 😄. It’s worth checking back here regularly for its ever-growing collection of technical articles – including, of course, lots of coverage on block development in a wide variety of use cases. The blog is also an excellent way to keep up with other developments in WordPress.

Perhaps you have an idea for an article in the Developer Blog. If so, why not propose the idea or even write it yourself. Here’s how!

6. Contributing

Like WordPress, Gutenberg is open-source software, and anyone is welcome to contribute to the project (this means you! 🫵). Get started with the Contributor Guide which details first steps and can help you choose how you want to contribute, whether with code, with testing, with documentation, or in some other way.

The handbook itself is undergoing continual improvement, and helping with that is an excellent and worthwhile way of making a contribution. The handbook is drawn from the docs directory of the Gutenberg repository. That repository has a label for developer documentation issues, namely [Type] Developer Documentation. Head over there, pick an issue, and start working on a PR.

If you’ve found a problem with the handbook, like an error or missing information, or even if you have an idea for improving the handbook, but you don’t want to create a pull request for it yourself, you can add an issue and label it with the [Type] Developer Documentation label. Someone will pick it up, and the handbook will get better and better over time.

And finally…

Once you’ve covered everything in this post, you’ll have a solid understanding of block development—both from a practical and a theoretical point of view. In addition to the above, take some time to simply browse through the handbook and explore its contents. Eventually, you will find that you know your way around the handbook, and you’ll find that you can locate the information you need, when you need it, far more easily.

Props to @ndiego, @marybaum, and @oglekler for reviewing this post.