Skip to content

Update block registration methods in documentation for WordPress 6.8+#76324

Merged
juanmaguitar merged 1 commit intotrunkfrom
docs/update-register-blocks-method
Mar 9, 2026
Merged

Update block registration methods in documentation for WordPress 6.8+#76324
juanmaguitar merged 1 commit intotrunkfrom
docs/update-register-blocks-method

Conversation

@juanmaguitar
Copy link
Copy Markdown
Contributor

What?

Updates the block registration documentation to cover the newer, more efficient registration APIs introduced in WordPress 6.7 and 6.8.

Why?

The current docs only describe register_block_type() for server-side block registration. WordPress 6.7 introduced wp_register_block_metadata_collection() and
WordPress 6.8 introduced wp_register_block_types_from_metadata_collection() — which is now the recommended approach and what @wordpress/create-block scaffolds by
default. The docs should reflect this.

How?

registration-of-a-block.md:

  • Restructured the "Registering a block with PHP" section into three subsections covering each approach in order of recommendation:
    1. wp_register_block_types_from_metadata_collection() (recommended, WP 6.8+)
    2. wp_register_block_metadata_collection() + individual register_block_type() (WP 6.7+)
    3. register_block_type() (single blocks or older WP versions)
  • Added callout boxes with version requirements and links to dev notes
  • Updated the Additional resources section with links to the new functions and dev notes

file-structure-of-a-block.md:

  • Updated the <plugin-file>.php section to mention wp_register_block_types_from_metadata_collection() as the recommended approach, with a cross-link to the full
    registration docs

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 9, 2026

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 <[email protected]>
Co-authored-by: ryanwelcher <[email protected]>

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

@ryanwelcher ryanwelcher added the [Type] Developer Documentation Documentation for developers label Mar 9, 2026
Copy link
Copy Markdown
Contributor

@ryanwelcher ryanwelcher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@juanmaguitar juanmaguitar enabled auto-merge (squash) March 9, 2026 15:29
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 9, 2026

Flaky tests detected in c906fa6.
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/22860111015
📝 Reported issues:

@juanmaguitar juanmaguitar merged commit 903eead into trunk Mar 9, 2026
46 of 48 checks passed
@juanmaguitar juanmaguitar deleted the docs/update-register-blocks-method branch March 9, 2026 15:49
@github-actions github-actions bot added this to the Gutenberg 22.8 milestone Mar 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants