The Block Editor Handbook is one of the primary resources for developers building with Gutenberg and WordPress core. Keeping it accurate and up-to-date as the editor evolves is an ongoing challenge.
Recently, a detailed Core Blocks reference section was proposed for the Handbook — providing structured API documentation for every block shipped in Gutenberg. The approach was to auto-generate these pages directly from each block’s block.json file, the single source of truth for a block’s attributes, supports, and metadata.
The initial pull request (#77350) was merged but subsequently reverted (#77590) due to insufficient community discussion before landing. That feedback was valid, and this post is the next step: bringing the proposal to the wider community before moving forward.
The updated proposal is in PR #77612: Docs — Auto-generate per-block API reference pages from block.json.
Understanding how a core block works today means reading its source code directly. A block is defined by attributes, supports, context, selectors, and parent/child relationships — but none of these are documented in context for any individual block. To learn about a specific block, a developer has to read its block.json file — which shows the values but does not explain what they mean — and then separately hunt through the general documentation to understand each property. Per-block documentation with contextual links to each concept would close that gap entirely.
The same problem affects LLMs: without documented context for each property, they have to parse source files to infer semantics, spending more tokens and filling context unnecessarily. This is important for AI-assisted creation of templates, template parts, patterns, and other block editor content.
Most of this detail already exists in the codebase. If it can be surfaced automatically, there’s no good reason to leave it buried.
The proposal introduces an automated pipeline that generates per-block API reference pages by reading each block’s block.json at build time. This means:
Every block shipped in Gutenberg automatically gets a documentation page reflecting its current attributes, supports, selectors, and other metadata.
Keeping docs in sync becomes a byproduct of keeping block.json accurate — which developers already do.
The Block Editor Handbook gains a canonical, always-current API reference for all core blocks.
The generated docs would live at paths like: developer.wordpress.org/block-editor/reference-guides/core-blocks/[block-name]/ and would look like this:
A key part of the proposal is that documentation is generated into a README.md file inside each block’s source directory — for example, packages/block-library/src/paragraph/README.md.
This follows the same convention already established for component documentation, where gen-components-docs generates a README.md inside each component’s directory at packages/components/src/{component}/README.md.
Having documentation live next to the code has a specific benefit: it allows hand-written narrative and auto-generated API reference to coexist in the same file. Generated content is wrapped in token delimiters (``), so any hand-written prose above the token is preserved across regenerations. The Navigation block README is a working example of this.
This mirrors the approach already used by the package API docs generator (update-api-docs.js) to document each package API inside each package README.md.
No separate docs PR is needed when you add or change a block.json attribute — the reference page updates automatically.
The README.md lives next to the block’s source, making the API surface discoverable when browsing the codebase.
The expectation for what constitutes “well-documented” becomes clearer and more tractable.
A reliable, auto-generated foundation means energy can be focused on narrative guides and tutorials rather than maintaining API reference tables.
Custom hand-written explanations in a block’s README.md are preserved across regenerations, so narrative docs and API reference can grow independently.
Having a public view of block documentation may encourage contributors to get involved by creating issues or PRs if they find errors.
README.md in the repo vs. the docs site: Should per-block README.md files live in the Gutenberg repository, or be generated solely at the docs site level (as PHP references currently are)?
Process fit: Does auto-generating docs from block.json fit naturally into the existing contribution workflow? Where might it break down?
block.json as source of truth: Are there things about a block that can’t or shouldn’t be derived from block.json? How should those gaps be handled?
Anything we’re missing: What challenges or risks hasn’t this proposal addressed?
Review the PR: #77612 — Docs: Auto-generate per-block API reference pages from block.json
Share feedback:
Comment on this post
Comment directly in the pull request discussion
Join the conversation live: We’ll be hosting a Hallway Hangout with Docs and Core team members approximately two weeks after this post. Details will be shared in the comments — watch this post if you’d like to join. The Meeting link will be shared in the #core-editor channel the day of the Hallway Hangout.
Milestone****DateFeedback period opens5th MayHallway Hangout18th May – 14:00 UTCFeedback period closes25th MayNext steps announcedShortly after close
Feedback collected from the community will help refine the proposal and inform next steps for implementation.
Props to @bph, @huzaifaalmesbah and @awetz583 for reviewing this post
#block-editor-handbook, #block-editor, #blocks, #docs, #handbooks
Fetched May 5, 2026
This month, the documentation brings improvements to some of our framework-specific guides, a big overhaul of the core visual editing docum…
