The proposal to auto-generate Block Editor Handbook pages from block.json fixes something that has bothered me for years: doc drift. If you have ever spent an hour inside packages/block-library working out why one attribute refuses to behave, you already know the problem.
Keeping the Block Editor Handbook in step with Gutenberg’s release cycle has been a losing fight for a long time. So developers read the source of core blocks instead, which works and also burns time and leaves plenty of room to guess wrong.
Why the docs fall behind
In a project moving as fast as Gutenberg, docs come last. The code changes, the feature ships, and at some point somebody maybe edits the markdown file. Every handbook page that is not generated from the code becomes debt, and the bill lands on whoever is building a custom block or extending a core one.
The accurate description of a block already lives in block.json. The public documentation is a separate file that somebody has to remember to update. That gap shows up in a few ways:
- New supports or context properties land in the code and never reach the docs.
- You bounce between GitHub, the handbook and your editor to work out what a block can actually do.
- AI assistants hand back outdated advice, because there is no structured, current API reference for them to read.
block.json as the source
The updated proposal in PR #77612 adds a build step that reads every block.json in the repo. Each block shipped with Gutenberg then gets one canonical documentation page describing what the code does today.
I wrote before about the WordPress documentation overhaul, and this follows from it. The generated reference goes into a README.md inside each block’s own directory, so it sits next to the code it describes.
A typical block.json already carries everything the generator needs:
{
"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
}
}
}Keeping hand-written prose with tokens
The usual objection to generated docs is that they read like dry tables with nothing human left in them. Gutenberg’s answer is token delimiters. Hand-written prose and the generated API reference sit in the same file, and only the part between the tokens gets rewritten at build time.
# 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 -->If handbook and block metadata work is eating your dev hours, I can take it on. I have been building on WordPress since the 4.x days.
What this means for contributors
Generating the reference is a stability fix more than a convenience. Once we auto-generate Block Editor Handbook pages from block.json, the drift between what a block can do and what the docs claim closes on its own. For a build step, that is cheap.
