Title: Navigating the Block Editor Handbook Author: Michael Burridge Published: June 20, 2023 --- * [Showcase](https://wordpress.org/showcase/) * [Plugins](https://wordpress.org/plugins/) * [Themes](https://wordpress.org/themes/) * [Hosting](https://wordpress.org/hosting/) * [News](https://wordpress.org/news/) - [Learn WordPress](https://learn.wordpress.org/) - [Documentation](https://wordpress.org/documentation/) - [Education](https://wordpress.org/education/) - [Forums](https://wordpress.org/support/forums/) - [Developers](https://developer.wordpress.org/) - [Blocks](https://wordpress.org/blocks/) - [Patterns](https://wordpress.org/patterns/) - [Photos](https://wordpress.org/photos/) - [Openverse ︎](https://openverse.org/) - [WordPress.tv ︎](https://wordpress.tv/) * - [About WordPress](https://wordpress.org/about/) - [Make WordPress](https://make.wordpress.org/) - [Events](https://events.wordpress.org/) - [Five for the Future](https://wordpress.org/five-for-the-future/) - [Enterprise](https://wordpress.org/enterprise/) - [Gutenberg ︎](https://wordpress.org/gutenberg/) - [Job Board ︎](https://jobs.wordpress.net/) * [Swag ︎](https://mercantile.wordpress.org/) * [Get WordPress](https://wordpress.org/download/) Search in WordPress.org [ Get WordPress ](https://wordpress.org/download/) [WordPress Developer Blog](https://developer.wordpress.org/news) * [Snippets](https://developer.wordpress.org/news/snippets/) - [Blocks](https://developer.wordpress.org/news/category/blocks/) - [Concepts](https://developer.wordpress.org/news/category/concepts/) - [Common APIs](https://developer.wordpress.org/news/category/common-apis/) - [Design](https://developer.wordpress.org/news/category/design/) - [Playground](https://developer.wordpress.org/news/category/playground/) - [Plugins](https://developer.wordpress.org/news/category/plugins/) - [Themes](https://developer.wordpress.org/news/category/themes/) * - [About this site](https://developer.wordpress.org/news/about/) - [Updates](https://developer.wordpress.org/news/category/updates/) - [How to contribute](https://developer.wordpress.org/news/how-to-contribute/) - [Tips and guidelines](https://developer.wordpress.org/news/tips-and-guidelines-for-writers/) * [Subscribe](https://developer.wordpress.org/news/subscribe/) * [Developer Resources](https://developer.wordpress.org/) * [Snippets](https://developer.wordpress.org/news/snippets/) - [Blocks](https://developer.wordpress.org/news/category/blocks/) - [Concepts](https://developer.wordpress.org/news/category/concepts/) - [Common APIs](https://developer.wordpress.org/news/category/common-apis/) - [Design](https://developer.wordpress.org/news/category/design/) - [Playground](https://developer.wordpress.org/news/category/playground/) - [Plugins](https://developer.wordpress.org/news/category/plugins/) - [Themes](https://developer.wordpress.org/news/category/themes/) * - [About this site](https://developer.wordpress.org/news/about/) - [Updates](https://developer.wordpress.org/news/category/updates/) - [How to contribute](https://developer.wordpress.org/news/how-to-contribute/) - [Tips and guidelines](https://developer.wordpress.org/news/tips-and-guidelines-for-writers/) * [Subscribe](https://developer.wordpress.org/news/subscribe/) * [Developer Resources](https://developer.wordpress.org/) # 󠀁[Navigating the Block Editor Handbook](https://developer.wordpress.org/news/2023/06/navigating-the-block-editor-handbook/)󠁿 By [Michael Burridge](https://profiles.wordpress.org/mburridge/) June 20, 2023 [Beginners](https://developer.wordpress.org/news/category/beginners/), [Blocks](https://developer.wordpress.org/news/category/blocks/), [Concepts](https://developer.wordpress.org/news/category/concepts/) ![Photograph of the pages of a book](https://developer.wordpress.org/news/files/ 2023/06/843646b4ac4ba1646.71094884.jpg) If you’re developing for the block editor, the [Block Editor Handbook](https://developer.wordpress.org/block-editor/) 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](https://github.com/WordPress/gutenberg/) 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: 1. It will kick off with an overview of the structure of the handbook. This will help you to orient yourself within it. 2. 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. 3. Next up is some guidance for if you’re working on a specific block project and need to find relevant information. 4. There then follows a curated selection of advanced topics. 5. A collection of links to other resources, separate from the handbook, that you can turn to for further help is up next. 6. 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](https://documentation.divio.com/). The Unified Theory separates documentation according to its purpose, i.e. learning, problem solving, understanding, and information. * **Tutorials** _(learning oriented) _– the [Getting Started](https://developer.wordpress.org/block-editor/getting-started/) section of the handbook leads you through the fundamentals of block development. * **How-to’s** _(problem oriented) _– the [How-to Guides](https://developer.wordpress.org/block-editor/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](https://developer.wordpress.org/block-editor/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](https://developer.wordpress.org/block-editor/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](https://wordpress.org/support/article/wordpress-editor/) itself, if you haven’t already. * Also, familiarize yourself with the components of the [user interface](https://developer.wordpress.org/block-editor/explanations/user-interface/). * Read the [Key Concepts](https://developer.wordpress.org/block-editor/explanations/architecture/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](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/), 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](https://developer.wordpress.org/block-editor/getting-started/devenv/). * Once you have a development environment you can move onto the [Create a Block Tutorial](https://developer.wordpress.org/block-editor/getting-started/create-block/) 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](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/). That section incrementally introduces the functionality you will need when building blocks. It refers to the code in the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples), 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](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-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](https://developer.wordpress.org/block-editor/how-to-guides/data-basics/) 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](https://developer.wordpress.org/block-editor/explanations/architecture/modularity/) 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](https://developer.wordpress.org/block-editor/explanations/architecture/) 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](https://developer.wordpress.org/block-editor/explanations/user-interface/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](https://developer.wordpress.org/block-editor/explanations/glossary/) to make sure you understand the terminology used in the handbook. * The [FAQs](https://developer.wordpress.org/block-editor/explanations/faq/) 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](https://developer.wordpress.org/block-editor/how-to-guides/) and [Reference Guides](https://developer.wordpress.org/block-editor/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](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar/) shows you how to add controls to the block’s interface so your users can interact with it and change settings. * [Notices](https://developer.wordpress.org/block-editor/how-to-guides/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](https://developer.wordpress.org/block-editor/how-to-guides/javascript/). * [Create your First App with Gutenberg Data](https://developer.wordpress.org/block-editor/how-to-guides/data-basics/) 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](https://developer.wordpress.org/block-editor/reference-guides/block-api/) very frequently. Your needs will vary, but almost every block development project will involve these basics: * [Registration](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/) * [Attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) * [Supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) * [Edit and Save](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/) It’s worth noting that if you use the [@wordpress/create-block](https://www.npmjs.com/package/@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](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/) 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. ![Screen grab of the documentation for the Button core block showing the link to the source code.](https://developer.wordpress.org/news/files/2023/06/image-3-1024x480. png) Each item in the Core Blocks Reference has a link to the source code for that block 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](https://developer.wordpress.org/block-editor/reference-guides/components/) details how to use each component. You can also use the accompanying [Storybook Tool](https://wordpress.github.io/gutenberg/) to interactively experiment with components to decide which ones you want to use in your project. The [Package Reference](https://developer.wordpress.org/block-editor/reference-guides/packages/) 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: * [@wordpress/components](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/)[ [source](https://github.com/WordPress/gutenberg/tree/trunk/packages/components)] * [@wordpress/block-editor](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/)[ [source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor)] * [@wordpress/rich-text](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-rich-text/)[ [source](https://github.com/WordPress/gutenberg/tree/trunk/packages/rich-text)] * [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)[ [source](https://github.com/WordPress/gutenberg/tree/trunk/packages/scripts)] ## 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: * [Deprecation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) * [Meta boxes](https://developer.wordpress.org/block-editor/how-to-guides/metabox/) * [Core Data Reference](https://developer.wordpress.org/block-editor/reference-guides/data/data-core/) * [Building a custom block editor](https://developer.wordpress.org/block-editor/how-to-guides/platform/custom-block-editor/) * [Slot/fill](https://developer.wordpress.org/block-editor/reference-guides/slotfills/) * [Extending the query loop block](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/extending-the-query-loop-block/) ## 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](https://learn.wordpress.org/): * [Introduction to Block Development: Build your first custom blockThis 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 BlockThis 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](https://learn.wordpress.org/course/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 ![Screengrab of the wordpress.tv website](https://developer.wordpress.org/news/files/ 2023/06/image-4-1024x1024.png) An ever-growing resource of videos ranging from talks at WordCamps to recordings of online workshops, [WordPress.tv](https://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](https://developer.wordpress.org/news/) 😄. 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](https://developer.wordpress.org/news/how-to-contribute/)! ## 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](https://developer.wordpress.org/block-editor/contributors/) 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](https://github.com/WordPress/gutenberg/tree/trunk/docs) directory of the Gutenberg repository. That repository has a label for developer documentation issues, namely [`[Type] Developer Documentation`](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Developer%20Documentation). 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](https://profiles.wordpress.org/ndiego/), [@marybaum](https://profiles.wordpress.org/marybaum/), and [@oglekler](https://profiles.wordpress.org/oglekler/) for reviewing this post._ **Categories:** [Beginners](https://developer.wordpress.org/news/category/beginners/), [Blocks](https://developer.wordpress.org/news/category/blocks/), [Concepts](https://developer.wordpress.org/news/category/concepts/) **Tags:** [Block development](https://developer.wordpress.org/news/tag/block-development/), [Extenders](https://developer.wordpress.org/news/tag/extenders/) ### Leave a Reply 󠀁[Cancel reply](https://developer.wordpress.org/news/2023/06/navigating-the-block-editor-handbook/?output_format=md#respond)󠁿 Your email address will not be published. Required fields are marked * Comment * Name * Email * Website Save my name, email, and website in this browser for the next time I comment. Notify me of follow-up comments by email. Notify me of new posts by email. Δ ## Have an idea for a new post? ### 󠀁[Learn how to contribute](https://developer.wordpress.org/news/how-to-contribute/)󠁿 Share your knowledge with fellow WordPress developers. Search ### 󠀁[Review tips and guidelines](https://developer.wordpress.org/news/tips-and-guidelines-for-writers/)󠁿 Everything you need to know about writing for the Blog. ## Subscribe to the Blog Email Address Join 1,773 other subscribers * [About](https://wordpress.org/about/) * [News](https://wordpress.org/news/) * [Hosting](https://wordpress.org/hosting/) * [Privacy](https://wordpress.org/about/privacy/) * [Showcase](https://wordpress.org/showcase/) * [Themes](https://wordpress.org/themes/) * [Plugins](https://wordpress.org/plugins/) * [Patterns](https://wordpress.org/patterns/) * [Learn](https://learn.wordpress.org/) * [Documentation](https://wordpress.org/documentation/) * [Developers](https://developer.wordpress.org/) * [WordPress.tv ](https://wordpress.tv/) * [Get Involved](https://make.wordpress.org/) * [Events](https://events.wordpress.org/) * [Donate ](https://wordpressfoundation.org/donate/) * [Swag ](https://mercantile.wordpress.org/) * [WordPress.com ](https://wordpress.com/?ref=wporg-footer) * [Matt ](https://ma.tt/) * [bbPress ](https://bbpress.org/) * [BuddyPress ](https://buddypress.org/) The WordPress® trademark is the intellectual property of the WordPress Foundation. * [Visit our X (formerly Twitter) account](https://www.x.com/WordPress) * [Visit our Bluesky account](https://bsky.app/profile/wordpress.org) * [Visit our Mastodon account](https://mastodon.world/@WordPress) * [Visit our Threads account](https://www.threads.net/@wordpress) * [Visit our Facebook page](https://www.facebook.com/WordPress/) * [Visit our Instagram account](https://www.instagram.com/wordpress/) * [Visit our LinkedIn account](https://www.linkedin.com/company/wordpress) * [Visit our TikTok account](https://www.tiktok.com/@wordpress) * [Visit our YouTube channel](https://www.youtube.com/wordpress) * [Visit our Tumblr account](https://wordpress.tumblr.com/)