Update block registration methods in documentation for WordPress 6.8+

docs/getting-started/fundamentals/file-structure-of-a-block.md

@@ -9,7 +9,7 @@ Adhering to the `create-block` tool's structure is not mandatory, but it serves
 ## `<plugin-file>.php`
 
 
-When creating a block in a WordPress plugin, you usually register the block on the server in the main PHP file of the plugin. This is done using the [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/) function. 
+When creating a block in a WordPress plugin, you register the block on the server in the main PHP file of the plugin. For plugins built with `wp-scripts` (WordPress 6.8+), the recommended approach is to use [`wp_register_block_types_from_metadata_collection()`](https://developer.wordpress.org/reference/functions/wp_register_block_types_from_metadata_collection/), which registers all blocks from a generated `blocks-manifest.php` file in a single call. For simpler setups or older WordPress versions, you can use [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/) to register individual blocks. See [Registration of a block](/docs/getting-started/fundamentals/registration-of-a-block.md) for full details on all available registration methods.
 
 <div class="callout callout-info">
     For more on creating a WordPress plugin, refer to the documentation on <a href="https://developer.wordpress.org/plugins/plugin-basics/">Plugin Basics</a> and the <a href="https://developer.wordpress.org/plugins/plugin-basics/header-requirements/"> Header Requirements</a> for the main PHP file.

docs/getting-started/fundamentals/registration-of-a-block.md

@@ -12,13 +12,62 @@ The following diagram details the registration process for a block.
 
 ## Registering a block with PHP (server-side)
 
-Block registration on the server usually takes place in the main plugin PHP file with the [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/) function called on the [`init`](https://developer.wordpress.org/reference/hooks/init/) hook. This function simplifies block type registration by reading metadata stored in a `block.json` file.
+Block registration on the server takes place in the main plugin PHP file, hooked on [`init`](https://developer.wordpress.org/reference/hooks/init/). WordPress provides several functions for this, depending on your needs and the minimum WordPress version you target.
 
-This function is designed to register block types and primarily uses two parameters in this context, although it can accommodate more variations:
+### Registering all blocks at once with a metadata collection (recommended)
 
-- **`$block_type` (`string`):** This can either be the path to the directory containing the `block.json` file or the complete path to the metadata file if it has a different name. This parameter tells WordPress where to find the block's configuration.
+Since WordPress 6.8, the recommended way to register blocks is [`wp_register_block_types_from_metadata_collection()`](https://developer.wordpress.org/reference/functions/wp_register_block_types_from_metadata_collection/). This function registers all block types defined in a `blocks-manifest.php` file in a single call, replacing the need for individual `register_block_type()` calls.
 
-- **`$args` (`array`):** This is an optional parameter where you can specify additional arguments for the block type. By default, this is an empty array, but it can include various options, one of which is the `$render_callback`. This callback is used to render blocks on the front end and is an alternative to the `render` property in `block.json`.
+The `blocks-manifest.php` file is automatically generated by the [`wp-scripts build-blocks-manifest`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#build-blocks-manifest) command (or by passing the `--blocks-manifest` flag to the `build` and `start` commands). It compiles metadata from all `block.json` files in your project into a single PHP file.
+
+```php
+function my_plugin_register_blocks() {
+	wp_register_block_types_from_metadata_collection(
+		__DIR__ . '/build',
+		__DIR__ . '/build/blocks-manifest.php'
+	);
+}
+add_action( 'init', 'my_plugin_register_blocks' );
+```
+
+This is the approach used by the [`create-block`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) scaffolding tool. It improves performance by avoiding reading multiple `block.json` files from disk, and it simplifies your plugin's registration code—especially for plugins with multiple blocks.
+
+<div class="callout callout-info">
+	<code>wp_register_block_types_from_metadata_collection()</code> requires WordPress 6.8 or later. See the <a href="https://make.wordpress.org/core/2025/03/13/more-efficient-block-type-registration-in-6-8/">WordPress 6.8 dev note</a> for more details.
+</div>
+
+### Registering a metadata collection separately (WordPress 6.7+)
+
+If you need more control over how individual blocks are registered (for example, to pass different `$args` to each block), you can use [`wp_register_block_metadata_collection()`](https://developer.wordpress.org/reference/functions/wp_register_block_metadata_collection/) to register the manifest first, then call `register_block_type()` for each block individually. WordPress will read each block's metadata from the already-loaded manifest instead of from disk.
+
+```php
+function my_plugin_register_blocks() {
+	wp_register_block_metadata_collection(
+		__DIR__ . '/build',
+		__DIR__ . '/build/blocks-manifest.php'
+	);
+
+	register_block_type( __DIR__ . '/build/block-one' );
+	register_block_type( __DIR__ . '/build/block-two', array(
+		'render_callback' => 'my_plugin_render_block_two',
+	) );
+}
+add_action( 'init', 'my_plugin_register_blocks' );
+```
+
+<div class="callout callout-info">
+	<code>wp_register_block_metadata_collection()</code> requires WordPress 6.7 or later. See the <a href="https://make.wordpress.org/core/2024/10/17/new-block-type-registration-apis-to-improve-performance-in-wordpress-6-7/">WordPress 6.7 dev note</a> for more details.
+</div>
+
+### Registering a single block with `register_block_type()`
+
+The [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/) function registers a single block type by reading metadata from a `block.json` file. This remains a valid approach, particularly for plugins with a single block or when targeting WordPress versions older than 6.7.
+
+This function primarily uses two parameters:
+
+- **`$block_type` (`string`):** The path to the directory containing the `block.json` file, or the full path to the metadata file if it has a different name.
+
+- **`$args` (`array`):** An optional array of additional arguments for the block type. This can include a `render_callback` as an alternative to the `render` property in `block.json`.
 
 During the development process, the `block.json` file is typically moved from the `src` (source) directory to the `build` directory as part of compiling your code. Therefore, when registering your block, ensure the `$block_type` path points to the `block.json` file within the `build` directory.
 
@@ -116,7 +165,11 @@ _See the [full block example](https://github.com/WordPress/block-development-exa
 
 ## Additional resources
 
+- [`wp_register_block_types_from_metadata_collection` PHP function](https://developer.wordpress.org/reference/functions/wp_register_block_types_from_metadata_collection/) (WordPress 6.8+)
+- [`wp_register_block_metadata_collection` PHP function](https://developer.wordpress.org/reference/functions/wp_register_block_metadata_collection/) (WordPress 6.7+)
 - [`register_block_type` PHP function](https://developer.wordpress.org/reference/functions/register_block_type/)
 - [`registerBlockType` JS function](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/#registerblocktype)
+- [More efficient block type registration in 6.8](https://make.wordpress.org/core/2025/03/13/more-efficient-block-type-registration-in-6-8/) | WordPress Core dev note
+- [New block type registration APIs in 6.7](https://make.wordpress.org/core/2024/10/17/new-block-type-registration-apis-to-improve-performance-in-wordpress-6-7/) | WordPress Core dev note
 - [Why a block needs to be registered in both the server and the client?](https://github.com/WordPress/gutenberg/discussions/55884) | GitHub Discussion
 - [Block Registration diagram](https://excalidraw.com/#json=PUQu7jpvbKsUHYfpHWn7s,61QnhpZtjykp3s44lbUN_g)