The Block Editor Handbook is a central resource for developers working with the Gutenberg editor and WordPress core. However, keeping its documentation accurate and up-to-date as the editor evolves is a persistent challenge. A new proposal aims to address this by auto-generating detailed per-block API reference pages directly from each block’s block.json file, the definitive source of a block’s attributes, supports, and metadata.
Key Takeaways
- The proposal introduces automated generation of per-block API reference docs from
block.jsonfiles for all Gutenberg core blocks. - Generated docs live as
README.mdfiles next to block source code, combining auto-generated API info with hand-written narrative. - This approach keeps documentation always in sync with code changes, reducing manual upkeep for developers and doc contributors.
- The proposal has been revised after initial community feedback and is now open for wider discussion and input.
- A scheduled feedback period and Hallway Hangout will gather community perspectives before finalizing implementation plans.
The Documentation Challenge for Core Blocks
For most WordPress sites and developers, understanding how a core block works means digging into the source code. Each block is defined by its attributes, supports, context, selectors, and parent/child relationships, but none of these details are currently documented in context for the individual block. Developers must read the raw block.json file, which lists values but offers no explanations, then cross-reference general documentation to interpret each property.
This fragmented approach complicates learning and slows down development. It also hinders AI-assisted tooling, such as large language models (LLMs), which must parse source files and infer semantics without explicit context. This inefficiency wastes tokens and reduces accuracy when generating templates, template parts, or block patterns.
Auto-generating block documentation from
block.jsonwould close the gap by providing contextual, canonical API references for every core block.
How the Proposal Works
The proposed solution introduces an automated pipeline that reads each block’s block.json file at build time to generate a per-block API reference page. This means every core block shipped in Gutenberg will have its own documentation page reflecting its current attributes, supports, selectors, and metadata.
The generated documentation is output as a README.md file inside each block’s source directory — for example, packages/block-library/src/paragraph/README.md. This method mirrors the existing practice for component documentation in the WordPress codebase, where API docs are generated alongside source files, such as packages/components/src/{component}/README.md.
Having the documentation live next to the code allows hand-written narrative and auto-generated API reference content to coexist in the same file. The generated sections are wrapped in token delimiters (<!-- START TOKEN / END TOKEN -->), preserving any prose above them across regenerations. The Navigation block’s README serves as a working example of this approach.
Benefits for Developers and Documentation Contributors
For block developers, this proposal means no separate documentation pull request is needed when updating block.json; the API reference updates automatically. This reduces friction and encourages keeping block.json accurate as the single source of truth. Documentation becomes more discoverable since the API surface lives alongside the code.
Documentation contributors can focus their efforts on narrative guides and tutorials rather than maintaining API tables. Since hand-written explanations in the README are preserved, narrative and API docs can evolve independently without conflicts.
For users of the Handbook, the docs will stay current with each Gutenberg release, reducing the risk of stale or outdated information. This consistency benefits both human developers and automated tooling that relies on accurate block metadata.
Community Feedback and Next Steps
The initial pull request to implement this feature was merged but later reverted due to insufficient community discussion. The updated proposal, now in PR #77612, aims to address those concerns by opening up the conversation widely before proceeding.
Key open questions include whether README.md files should live in the Gutenberg repository or be generated solely for the documentation site, how well this approach fits into existing contribution workflows, and whether there are any block details that cannot be derived from block.json.
Community members are encouraged to review the PR, comment on the proposal, and join a scheduled Hallway Hangout with Docs and Core team members on May 18th, 2026, at 14:00 UTC. Feedback will be collected through May 25th and used to refine the implementation plan.
What This Means for WordPress Users
We see this proposal as a meaningful step toward improving the developer experience around WordPress core blocks. For developers, automatic synchronization between block metadata and documentation reduces overhead and the risk of documentation drift, which can lead to confusion or implementation errors.
Agencies and freelancers maintaining custom blocks or extending core blocks will benefit from clearer, always up-to-date references, speeding development and easing onboarding. The approach also signals a shift toward treating block.json as the authoritative source of block configuration and documentation, reinforcing best practices.
From a broader ecosystem perspective, surfacing structured block metadata as documentation aligns well with AI-assisted development workflows. As large language models and automated tools become more prevalent, having precise, contextual documentation embedded in the source code will improve their accuracy and utility.
We recommend WordPress developers and documentation contributors review the proposal and participate in the discussion. Engaging early helps shape the final implementation to best meet the community’s needs and avoid pitfalls.
Frequently Asked Questions
Why is the documentation generated from block.json instead of manually written?
Because block.json is the definitive source for block attributes and metadata, generating docs from it ensures accuracy and keeps documentation in sync with code changes. Manual docs often lag behind and require more maintenance.
Can developers still add custom narrative documentation?
Yes. The generated README files allow hand-written prose above the auto-generated sections, so narrative descriptions and examples can coexist with API references.
How will this affect contributions to the Block Editor Handbook?
By automating API reference generation, contributors can focus more on tutorials and guides, reducing duplication and making it easier to keep docs current with Gutenberg releases.
What if some block details can’t be represented in block.json?
The proposal seeks feedback on these gaps. For properties not expressible in block.json, additional manual documentation or extensions may be necessary to provide complete context.
