Docs: Auto-generate per-block API reference pages from block.json

[juanmaguitar]

What?

Important

The post Proposal: Auto-generate Block Editor Handbook docs from block.json was published on make.wordpress.org/core to gather feedback about this proposal and a hallway hangout was held to explain the outcome of the PR and receive feedback. All feedback and technical concerns have been addressed. See related comment

Continuation of #77350, which was merged and later reverted in #77590 after concerns were raised about a lack of consensus.

core-blocks-docs-demo.mp4

This PR, built on top of the work started by @jonathanbossenger, adds auto-generated per-block API reference pages following the same approach already used for component documentation in this repo:

• A generator script reads source metadata and produces a README.md inside each block's source directory (packages/block-library/src/{block}/README.md), just as gen-components-docs generates README.md files inside each component's directory (packages/components/src/{component}/README.md).
• The manifest builder scans these READMEs and adds them to the handbook via a {{blocks}} token in toc.json, following the existing {{components}} and {{packages}} pattern.
• Generated content uses <!-- START TOKEN / END TOKEN --> delimiters so hand-written content in existing READMEs is preserved — the same convention used by the package API docs generator (update-api-docs.js).

These pages are wired into the Block Editor Handbook manifest as a 3-level hierarchy: Core Blocks Reference → Category → Block.

Why?

The only official documentation for core blocks is the flat summary at Core Blocks Reference. It lists block names, supports, and attribute keys — but lacks detail on attribute types, defaults, context, CSS selectors, styles, and block markup patterns.

Developers working with core blocks need this information and currently have to dig through source code. Having structured, per-block reference pages makes the block API surface discoverable and keeps the documentation in sync with the codebase via a generator script.

How?

New script: tools/api-docs/generate-block-docs.mjs

Reads each block's block.json and source file structure, then generates:

• 121 block README.md files in packages/block-library/src/{block}/ — each containing attributes table (types, defaults, source, selector, role), supports detail, context (uses/provides), block styles, CSS selectors, block markup examples, and source file links.
• 8 category index pages in docs/reference-guides/core-blocks/category-{cat}.md — listing blocks in each category with links to their handbook pages.

Token-delimited content — generated content is wrapped in <!-- START TOKEN(Autogenerated block API docs) --> / <!-- END TOKEN(...) --> delimiters, following the same pattern used by the existing package API docs generator. This means:

• Blocks with no existing README get a new file with title + generated content.
• Blocks with existing hand-written READMEs (e.g., navigation, social-link) keep their content intact — generated API reference is appended below the hand-written prose, and only the content between tokens is updated on subsequent runs.

Cross-linking throughout — generated pages link to relevant reference docs:

• Supports properties link to their entry on the Block Supports reference (both top-level and sub-properties that have dedicated anchors).
• Block Relationships (parent, ancestor, allowedBlocks) link to the Block Metadata reference and to each related block's own detail page.
• Category links to its category index page, API Version links to the API Versions reference, Block Type links to the Static & Dynamic Rendering guide.
• Each section (Attributes, Supports, Context, Styles, Selectors) includes an intro line linking to the relevant block.json property reference (e.g., "Defined via the attributes property in block.json.").
• Source section links block.json to both the GitHub source and the Block Metadata reference.

Updated: tools/api-docs/gen-block-lib-list.js

The existing summary page generator (core-blocks.md) now:

• Links each block name to its detail page (e.g., **Name:** [core/accordion](/block-editor/...)).
• Links each category to its category index page.
• Removes the ([Source](...)) link after each description (source links are now in each block's detail page).

Manifest integration

• docs/toc.json — core-blocks.md entry updated from [] to "{{blocks}}", following the existing {{components}} and {{packages}} pattern.
• docs/tool/manifest.js — new getBlockManifest() function reads block.json files directly for metadata (title, category) instead of parsing markdown. Points markdown_source to ../packages/block-library/src/{block}/README.md. Produces a 3-level hierarchy:
  • Category pages → parent: 'core-blocks', slug: core-blocks-{category}
  • Block pages → parent: 'core-blocks-{category}', slug: core-block-{blockname}

Build pipeline & keeping docs in sync

The per-block docs follow the exact same commit-time flow as the existing API docs (docs:api-ref) and component docs — no new machinery, no CI step.

Scripts

• New npm script docs:blocks-detail runs the generator (generate-block-docs.mjs).
• It's added to the docs:build pipeline so a full build regenerates everything.

Automatic regeneration on commit (lint-staged)

• docs:blocks-detail is added to the existing packages/**/*.{js,ts,tsx,json} lint-staged entry, alongside docs:api-ref and docs:blocks. So whenever a block.json (or any package source file) is committed, the block READMEs are regenerated.
• The generator rewrites all block READMEs, but only those whose content actually changed differ — and only the content between the START/END TOKEN delimiters is touched, so hand-written prose is preserved.

The sync gate

• The generator's output is not auto-committed: .md files aren't matched by the glob, so lint-staged never stages them.
• The existing docs:check-api-docs-unstaged check — already in the same lint-staged entry — detects any README carrying the <!-- START TOKEN --> marker that the generator just changed (block READMEs included) and fails the commit.
• When a task fails, lint-staged rolls back its changes (it stashes the original state at the start), so the hook's regeneration is discarded. Its job is to detect and block, not to commit the docs for you.
• To get past the gate, the developer runs npm run docs:build (or docs:blocks-detail), stages the updated READMEs, and re-commits — or bypasses with --no-verify. This is identical to how stale API/component docs are handled today.

Manifest regeneration

• packages/block-library/src/*/README.md is added to the manifest-regeneration glob (docs:gen), mirroring the existing components/src/*/**/README.md entry. getBlockManifest() only includes a block whose README exists, so creating or removing a block README triggers a manifest rebuild.

Notes on scope (by design)

• Because the generator regenerates all blocks (not just the changed one), any drift left behind by an earlier --no-verify commit or a trunk merge is surfaced and corrected by the next regular commit — the docs self-heal.
• Regeneration is cheap (~0.4s for all 121 blocks; the docs:api-ref step in the same hook dominates at ~18s), so the added cost per commit is negligible.

Testing Instructions

Markdown docs generation

git clone https://github.com/WordPress/gutenberg.git
cd gutenberg
git checkout build/docs-blocks-generation-v2
npm install

This PR includes the generated files. To properly test the generation of files we need to restore the state of .md files to trunk:

# 1. Restore block READMEs to trunk state (reverts generated content, keeps hand-written content, deletes READMEs that didn't exist before)
git checkout trunk -- 'packages/block-library/src/*/README.md'

# 2. Remove new READMEs that don't exist on trunk (newly created by the script)
git diff --name-only --diff-filter=A trunk -- 'packages/block-library/src/*/README.md' | xargs rm -f

# 3. Remove category pages (all new, don't exist on trunk)
rm -f docs/reference-guides/core-blocks/category-*.md

# 4. Restore other generated files to trunk state
git checkout trunk -- docs/manifest.json docs/reference-guides/core-blocks.md

1. Generate block reference pages:

npm run docs:blocks-detail

Check packages/block-library/src/ — each block directory should now have a README.md with token-delimited API reference content. Also check docs/reference-guides/core-blocks/ for the 8 category-*.md files.

2. Verify hand-written READMEs are preserved:
Check packages/block-library/src/navigation/README.md — the hand-written CSS classes documentation should appear above the <!-- START TOKEN --> delimiter, with the generated API reference below it.

3. Verify the summary page:

npm run docs:blocks

Open docs/reference-guides/core-blocks.md — block names should link to their detail pages and categories should link to their index pages.

4. Verify the manifest:

node docs/tool/index.js

Open docs/manifest.json and find core-block-paragraph. Its parent should be core-blocks-text, and markdown_source should point to ../packages/block-library/src/paragraph/README.md.

Rendered handbook pages

1. Set up wporg-developer (if not already):

git clone https://github.com/WordPress/wporg-developer.git
cd wporg-developer && composer install && npm install
npm run wp-env start
yarn setup

If you already have an existing setup, update the wporg-markdown plugin to pick up the fix from wordpress.org@870a792 (which removes the posts_per_page limit in the importer - see WordPress/wporg-developer#564):

svn up source/wp-content/plugins/wporg-markdown

2. Point the importer to this PR. Edit source/wp-content/themes/wporg-developer-2023/inc/import-block-editor.php and replace the manifest URL:

$manifest = 'https://raw.githubusercontent.com/WordPress/gutenberg/refs/pull/77612/head/docs/manifest.json';

3. Run the import:

npm run wp-env run cli wp cron event run devhub_blocks_import_manifest
npm run wp-env run cli wp cron event run devhub_blocks_import_all_markdown

4. Verify at http://localhost:8888/block-editor/reference-guides/core-blocks/:

• The sidebar shows a 3-level hierarchy: Core Blocks Reference → Category → Block
• Clicking a block page renders the attributes table, supports with links, block markup example, etc.
• Category pages list their blocks with working links
• Existing handbook sections (Components, Packages, Interactivity API) still appear in the sidebar

Use of AI Tools

This PR was co-authored with Claude Code (Claude Opus). The generator script, manifest integration, and PR description were AI-assisted. All output was reviewed for accuracy against the existing codebase conventions and tested locally.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: andreawetzel <awetz583@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: bph <bph@git.wordpress.org>
Co-authored-by: joedolson <joedolson@git.wordpress.org>
Co-authored-by: dd32 <dd32@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: 0 B

Total Size: 8.21 MB

_{compressed-size-action}

[github-actions]

Flaky tests detected in 07961d3.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27067091738
📝 Reported issues:

• [Flaky Test] Should save the changes #78689 in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js
• [Flaky Test] should allow user to add and remove multiple local font files #78760 in /test/e2e/specs/admin/font-library.spec.js

[juanmaguitar]

@Mamaduka @ciampo @manzoorwanijk — since you flagged a lack of consensus that led to the revert of #77350, could you advise on what next steps would give this PR a real chance to move forward? What would be required from your perspective to merge this?

[t-hamano]

@juanmaguitar, Do you mind rebasing this PR on top of trunk? This should eliminate the unintended "Common blocks" category. See #61916

[andreawetzel]

I was able to test the markdown docs generation steps and the files looked good to me. I confirmed that recently renamed blocks such as Verse/Poetry and Page Title/Title are using the correct new names.

[manzoorwanijk]

I think this is good to merge after addressing the concern raised by @t-hamano in #77612 (comment)

[t-hamano]

Thank you for your continued work on this PR. After this PR is released, let's make improvements as needed based on community feedback.

[Mamaduka]

Thanks, @juanmaguitar! Nice work all around!