Docs: Auto-generate per-block API reference pages from block.json#77612
Open
juanmaguitar wants to merge 42 commits intotrunkfrom
Open
Docs: Auto-generate per-block API reference pages from block.json#77612juanmaguitar wants to merge 42 commits intotrunkfrom
juanmaguitar wants to merge 42 commits intotrunkfrom
Conversation
juanmaguitar
requested review from
ajitbohra,
fabiankaegy,
nerrad and
ntwb
as code owners
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
juanmaguitar
added
the
[Type] Developer Documentation
|
Size Change: 0 B Total Size: 7.82 MB ℹ️ View Unchanged
|
|
Flaky tests detected in 655225d. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25101879820
|
Contributor
Author
|
@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? |
Contributor
|
@juanmaguitar, Do you mind rebasing this PR on top of trunk? This should eliminate the unintended "Common blocks" category. See #61916 |
t-hamano
reviewed
Apr 24, 2026
…cript - Created README.md files for the following blocks: - core/template-part - core/term-count - core/term-description - core/term-name - core/term-template - core/terms-query - core/text-columns (deprecated) - core/verse - core/video - Implemented a new script to automate the generation of block documentation from block.json files, ensuring consistent formatting and inclusion of relevant metadata.
…for core blocks - Updated parent, ancestor, and allowed inner blocks in various block README files to use markdown links for better navigation. - Implemented a new function in the documentation generation script to automatically create links based on block names and their categories.
- Updated README files for various blocks to include links to the Block Supports reference for each property. - Improved the `generate-block-docs.mjs` script to automatically generate these links based on property names. - Ensured that all relevant properties in the documentation are now clickable, providing easier access to detailed information.
…onsistency - Updated links in README.md files across various blocks to replace dots with hyphens in the URLs for block supports. - Adjusted the `generate-block-docs.mjs` script to ensure that links are generated with hyphens instead of dots.
…tion - Updated block supports documentation across multiple blocks to remove unnecessary array notation for properties such as `margin`, `padding`, and `clientNavigation`. - Enhanced the `generate-block-docs` script to improve the handling of sub-properties in the documentation links, ensuring that only relevant properties have dedicated anchors.
…ion script to create headers without descriptions.
…ons, and block types; enhance attribute, support, context, and style sections with definitions; and standardize dynamic, hybrid, and static block descriptions with links to the rendering guide.
…n-block-lib-list.js
… allowed inner blocks - Added markdown links for "Parent blocks (direct)" in various block README files to reference the block metadata documentation. - Updated "Ancestor blocks" sections to include links in relevant README files. - Modified "Allowed inner blocks" sections to include links in applicable README files. - Adjusted the `generate-block-docs.mjs` script to automatically format these links in the generated documentation.
- Updated attribute tables across multiple block README files to standardize the format for Type and Default columns. - Enhanced descriptions to include links to relevant sections in the block attributes documentation. - Added validation for attribute anchors in the documentation generation script to ensure consistency with the block attributes reference.
…AttributeAnchors function
…anchor validation logic
…xitCode on errors
Also improved "repoRoot" location so the script can be run from anywhere
Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>
…l warnings - Updated README.md files for various blocks to display fixtures as examples for each block - Added experimental warnings to blocks that are marked as experimental. - Changed the documentation generation script to include a check for existing fixture files, and updated the source file references to point to the source directory instead of individual files.
…ze "experimental" status
…mple generation - solved lint issues
- Removed the 'common' category and moved relevant blocks (form, input field, submission notification, submit button) to the 'widgets' category. - Updated documentation links and descriptions for the 'tab' and 'tab panel' blocks, introducing 'tab list' and 'tab panels' blocks. - Deleted the 'tabs menu item' block and adjusted related documentation accordingly. - Enhanced README files for various blocks to reflect new relationships and attributes.
juanmaguitar
force-pushed
the
build/docs-blocks-generation-v2
branch
from
b546ad3 to
7fcae3d
Compare
Member
|
Maybe we could autogenerate similar to on the docs site, IIRC that how PHP references are created. Currently, I don’t really see a good reason why these files should be tracked in this repo. cc @dd32 do you have any pointers? |
Contributor
Author
For more context, this logic is using the same strategy than the IMO there's value to have a |
Contributor
Author
|
- Improved descriptions for various blocks including `core/query-total`, `core/query`, `core/quote`, and others to provide clearer context and usage. - Standardized formatting in README files by changing bullet points for metadata sections. - Ensured consistency across all block documentation by aligning the structure and style.
- Changed the reference in toc.json from core-blocks.md to core-blocks/README.md. - Updated the output path in gen-block-lib-list.js to publish to core-blocks/README.md instead of core-blocks.md.
juanmaguitar
added
[Type] Enhancement
t-hamano
added
[Type] Developer Documentation
Contributor
|
Your feedback would be appreciated @WordPress/outreach This is would bring the Block Editor handbook section for single blocks updated, enhanced and also more maintainable. |
t-hamano
reviewed
Apr 29, 2026
| @@ -0,0 +1,26 @@ | |||
| # Design Blocks | |||
|
|
|||
| - [Accordion](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-accordion/) — `core/accordion`: Displays a foldable layout that groups content in collapsible sections. | |||
Contributor
There was a problem hiding this comment.
I think these category files are created manually. Is it possible to automate their generation? This is how the file should look.
# Design Blocks
<!-- START TOKEN(Autogenerated block API docs) -->
A list of auto-generated blocks will go here.
<!-- END TOKEN(Autogenerated block API docs) -->
| @@ -0,0 +1,1153 @@ | |||
| # Core Blocks Reference | |||
Contributor
There was a problem hiding this comment.
Since individual pages have been created for each block, I don't think we need to list all the blocks on this page. Perhaps links to each block category would be sufficient?
Contributor
|
For accessibility purposes, I'd love to also include documentation on known accessibility status for blocks. For content authors who need to meet accessibility standards, it would be useful for them to know what potential issues exist with a block. There are limitations to what we can reasonably document - e.g., any block with color settings can potentially violate color contrast guidelines - but there are also key cases, like the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
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:
README.mdinside each block's source directory (packages/block-library/src/{block}/README.md), just asgen-components-docsgeneratesREADME.mdfiles inside each component's directory (packages/components/src/{component}/README.md).{{blocks}}token intoc.json, following the existing{{components}}and{{packages}}pattern.<!-- 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.mjsReads each block's
block.jsonand source file structure, then generates: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.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: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:
block.jsonproperty reference (e.g., "Defined via theattributesproperty in block.json.").block.jsonto both the GitHub source and the Block Metadata reference.Updated:
tools/api-docs/gen-block-lib-list.jsThe existing summary page generator (
core-blocks.md) now:**Name:** [core/accordion](/block-editor/...)).([Source](...))link after each description (source links are now in each block's detail page).Manifest integration
docs/toc.json—core-blocks.mdentry updated from[]to"{{blocks}}", following the existing{{components}}and{{packages}}pattern.docs/tool/manifest.js— newgetBlockManifest()function readsblock.jsonfiles directly for metadata (title, category) instead of parsing markdown. Pointsmarkdown_sourceto../packages/block-library/src/{block}/README.md. Produces a 3-level hierarchy:parent: 'core-blocks', slug:core-blocks-{category}parent: 'core-blocks-{category}', slug:core-block-{blockname}Build pipeline
docs:blocks-detailruns the generator.docs:buildpipeline and lint-staged config, so pages are regenerated automatically whenblock.jsonfiles change.packages/block-library/src/*/README.mdadded to the manifest regeneration trigger glob.Testing Instructions
Markdown docs generation
git clone https://github.com/WordPress/gutenberg.git cd gutenberg git checkout build/docs-blocks-generation-v2 npm installThis PR includes the generated files. To properly test the generation of files we need to restore the state of .md files to trunk:
1. Generate block reference pages:
Check
packages/block-library/src/— each block directory should now have aREADME.mdwith token-delimited API reference content. Also checkdocs/reference-guides/core-blocks/for the 8category-*.mdfiles.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:
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:
Open
docs/manifest.jsonand findcore-block-paragraph. Itsparentshould becore-blocks-text, andmarkdown_sourceshould point to../packages/block-library/src/paragraph/README.md.Rendered handbook pages
1. Set up wporg-developer (if not already):
If you already have an existing setup, update the
wporg-markdownplugin to pick up the fix from wordpress.org@870a792 (which removes theposts_per_pagelimit in the importer - see WordPress/wporg-developer#564):2. Point the importer to this PR. Edit
source/wp-content/themes/wporg-developer-2023/inc/import-block-editor.phpand replace the manifest URL:3. Run the import:
4. Verify at
http://localhost:8888/block-editor/reference-guides/core-blocks/: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.