The latest proposal to Auto-generate Block Editor Handbook documentation from block.json is a game-changer for anyone tired of “doc-drift.” If you have ever spent an hour digging through packages/block-library source code just to find out why a specific attribute isn’t behaving, you know exactly why this matters.
For years, keeping the Block Editor Handbook in sync with Gutenberg’s rapid release cycle has been a losing battle. Consequently, developers often resort to reading the raw source code of core blocks to understand their internal API. This is inefficient, prone to error, and honestly, a bottleneck for the entire ecosystem.
The Problem: Documentation is a Liability
In a complex project like Gutenberg, documentation is often treated as an afterthought. We update the code, ship the feature, and maybe—if we’re lucky—someone updates the markdown file. However, when we don’t Auto-generate Block Editor Handbook pages, we create a technical debt that hurts every developer trying to build custom blocks or extend core ones.
The current workflow is broken because the “Single Source of Truth” is buried in block.json, while the public-facing documentation is a separate, manually maintained entity. This leads to several issues:
- Inaccurate Attributes: New supports or context properties are added to code but never documented.
- Context Switching: Devs have to jump between GitHub, the Handbook, and their IDE to piece together a block’s capabilities.
- LLM Hallucinations: AI assistants often provide outdated advice because they lack structured, up-to-date API references.
The Solution: Using block.json as the Source
The updated proposal in PR #77612 suggests an automated pipeline that reads every block.json file at build time. Therefore, every block shipped in Gutenberg will automatically receive a canonical documentation page reflecting its current state.
I’ve written before about the WordPress documentation overhaul, and this is the logical next step. By generating documentation into a README.md file inside each block’s source directory, the reference stays close to the code.
Here is how a typical block.json might be structured, providing all the metadata needed for generation:
{
"apiVersion": 3,
"name": "core/paragraph",
"title": "Paragraph",
"category": "text",
"attributes": {
"content": {
"type": "string",
"source": "html",
"selector": "p",
"default": ""
},
"dropCap": {
"type": "boolean",
"default": false
}
},
"supports": {
"anchor": true,
"typography": {
"fontSize": true,
"lineHeight": true
}
}
}Preserving Narrative with Tokens
One common critique of auto-generated docs is that they lack “soul”—they are just dry tables. The Gutenberg team is solving this using token delimiters. Specifically, hand-written prose can coexist with the generated API reference.
# Paragraph Block
This block is the fundamental building block of the editor.
<!-- START TOKEN: BLOCK_API -->
Auto-generated content will be injected here during build...
<!-- END TOKEN: BLOCK_API -->Look, if this Block Editor Handbook stuff is eating up your dev hours, let me handle it. I’ve been wrestling with WordPress since the 4.x days.
Final Takeaway for Contributors
Automating the reference guide is not just about convenience; it’s about stability. When we Auto-generate Block Editor Handbook docs, we ensure that the “drift” between what a block can do and what we say it can do is eliminated. This is a pragmatic step forward that every WordPress developer should support.
