X-post: Proposal: Buat dokumen Panduan Editor Blok secara otomatis dari block.json

The Block Editor Handbook is one of the primary resources for developers building with Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ and WordPress core Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. 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 An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. documentation for every block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. 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.

The problem

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 JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. 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 proposed solution

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:

README.md per block in the repository

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 (<!-- START TOKEN / END TOKEN -->), 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.

What this means for contributors

For block developers

• 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.

For documentation contributors

• 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.

For users of the Handbook

• Reference pages stay current with each Gutenberg release rather than drifting behind.

Open questions — we want your input

1. 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 The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher references currently are)?
2. Process fit: Does auto-generating docs from block.json fit naturally into the existing contribution workflow? Where might it break down?
3. 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?
4. Anything we’re missing: What challenges or risks hasn’t this proposal addressed?

Get involved

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.

Timeline

Milestone	Date
Feedback period opens	5th May
Hallway Hangout	18th May – 14:00 UTC
Feedback period closes	25th May
Next steps announced	Shortly 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