prep build 01/25

docs/getting-started/fundamentals/block-in-the-editor.md

@@ -3,6 +3,7 @@
 The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component defined in the `edit` property of the settings object used to [register the block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side). 
 
 The `props` object received by the block's `Edit` React component includes:
+
 - [`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes) - attributes object
 - [`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes) - method to update the attributes object
 - [`isSelected`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#isselected) - boolean that communicates whether the block is currently selected
@@ -14,18 +15,21 @@ The WordPress Gutenberg project uses <a href="https://wordpress.github.io/gutenb
 </div>
 
 Custom settings controls for the block in the Block Toolbar or the Settings Sidebar can also be defined through this `Edit` React component via built-in components such as:
+
 - [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md) 
 - [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls) 
 
 ## Built-in components
 
 The package [`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) includes a library of generic WordPress components to create common UI elements for the Block Editor and the WordPress dashboard. Some of the  most commonly used components from this package are:
+
 - [`TextControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-textcontrol--docs) 
 - [`Panel`](https://wordpress.github.io/gutenberg/?path=/docs/components-panel--docs)
 - [`ToggleControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-togglecontrol--docs)
 - [`ExternalLink`](https://wordpress.github.io/gutenberg/?path=/docs/components-externallink--docs)
 
 The package [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) includes a library of components and hooks for the Block Editor, including those to define custom settings controls for the block in the Editor. Some of the components most commonly used from this package are:
+
 - [`RichText`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md)
 - [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)
 - [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
@@ -37,13 +41,12 @@ The package <a href="https://developer.wordpress.org/block-editor/reference-guid
 </div>
 
 A good workflow when using a component for the Block Editor is:
+
 - Import the component from a WordPress package
 - Add the corresponding code for the component to your project in JSX format
 - Most built-in components will be used to set [block attributes](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#using-attributes-to-store-block-data), so define any necessary attributes in `block.json` and create event handlers to update those attributes with `setAttributes` in your component
 - If needed, adapt the code to be serialized and stored in the database
 
-
-
 ## Block Controls: Block Toolbar and Settings Sidebar
 
 To simplify block customization and ensure a consistent experience for users, there are a number of built-in UI patterns to help generate the editor preview. 
@@ -95,7 +98,6 @@ _See the [full block example](https://github.com/WordPress/block-development-exa
 
 Note that `BlockControls` is only visible when the block is currently selected and in visual editing mode. `BlockControls` are not shown when editing a block in HTML editing mode.
 
-
 ### Settings Sidebar
 
 The Settings Sidebar is used to display less-often-used settings or settings that require more screen space. The Settings Sidebar should be used for **block-level settings only**.

docs/getting-started/fundamentals/block-wrapper.md

@@ -2,16 +2,16 @@
 
 Each block's markup is wrapped by a container HTML tag that needs to have the proper attributes to fully work in the Block Editor and to reflect the proper block's style settings when rendered in the Block Editor and the front end. As developers, we have full control over the block's markup, and WordPress provides the tools to add the attributes that need to exist on the wrapper to our block's markup.
 
-Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`. 
+Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`.
 
 <div class="callout callout-info">
 The use of <code>supports</code> generates a set of properties that need to be manually added to the wrapping element of the block so they're properly stored as part of the block data.
 </div>
 
 A block can have three sets of markup defined, each one of them with a specific target and purpose:
 
-- The one for the **Block Editor**, defined through a `edit` React component passed to [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#registerblocktype) when registering the block in the client. 
-- The one used to **save the block in the DB**, defined through a `save` function passed to `registerBlockType` when registering the block in the client. 
+- The one for the **Block Editor**, defined through a `edit` React component passed to [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#registerblocktype) when registering the block in the client.
+- The one used to **save the block in the DB**, defined through a `save` function passed to `registerBlockType` when registering the block in the client.
     - This markup will be returned to the front end on request if no dynamic render has been defined for the block.
 - The one used to **dynamically render the markup of the block** returned to the front end on request, defined through the `render_callback` on [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) or the [`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render) PHP file in `block.json`
     - If defined, this server-side generated markup will be returned to the front end, ignoring the markup stored in DB.
@@ -21,13 +21,14 @@ For the [`edit` React component and the `save` function](https://developer.wordp
 
 ## The Edit component's markup
 
-The [`useBlockProps()`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops) hook available on the [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor) allows passing the required attributes for the Block Editor to the `edit` block's outer wrapper. 
+The [`useBlockProps()`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops) hook available on the [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor) allows passing the required attributes for the Block Editor to the `edit` block's outer wrapper.
 
 Among other things, the `useBlockProps()` hook takes care of including in this wrapper:
-- An `id` for the block's markup 
-- Some accesibility and `data-` attributes
+
+- An `id` for the block's markup
+- Some accessibility and `data-` attributes
 - Classes and inline styles reflecting custom settings, which include by default:
-    - The `wp-block` class 
+    - The `wp-block` class
     - A class that contains the name of the block with its namespace
 
 For example, for the following piece of code of a block's registration in the client...
@@ -43,18 +44,18 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
 
 ...the markup of the block in the Block Editor could look like this:
 ```html
-<p 
-    tabindex="0" 
-    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
-    role="document" 
-    aria-label="Block: Minimal Gutenberg Block ca6eda" 
-    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
-    data-type="block-development-examples/minimal-block-ca6eda" 
-    data-title="Minimal Gutenberg Block ca6eda" 
+<p
+    tabindex="0"
+    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe"
+    role="document"
+    aria-label="Block: Minimal Gutenberg Block ca6eda"
+    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe"
+    data-type="block-development-examples/minimal-block-ca6eda"
+    data-title="Minimal Gutenberg Block ca6eda"
     class="
-        block-editor-block-list__block 
-        wp-block 
-        is-selected 
+        block-editor-block-list__block
+        wp-block
+        is-selected
         wp-block-block-development-examples-minimal-block-ca6eda
     "
 >Hello World - Block Editor</p>
@@ -87,16 +88,16 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
 <p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – Frontend</p>
 ```
 
-Any additional classes and attributes for the `save` function of the block should be passed as an argument of `useBlockProps.save()` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)). 
+Any additional classes and attributes for the `save` function of the block should be passed as an argument of `useBlockProps.save()` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)).
 
 When you add `supports` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.
 
 ```html
 <p class="
-    wp-block-block-development-examples-block-supports-6aa4dd 
-    has-accent-4-color 
-    has-contrast-background-color 
-    has-text-color 
+    wp-block-block-development-examples-block-supports-6aa4dd
+    has-accent-4-color
+    has-contrast-background-color
+    has-text-color
     has-background
 ">Hello World</p>
 ```
@@ -105,10 +106,10 @@ _(check the [example](https://github.com/WordPress/block-development-examples/tr
 
 ## The server-side render markup
 
-Any markup in the server-side render definition for the block can use the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) function to generate the string of attributes required to reflect the block settings (see [example](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)). 
+Any markup in the server-side render definition for the block can use the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) function to generate the string of attributes required to reflect the block settings (see [example](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)).
 
 ```php
 <p <?php echo get_block_wrapper_attributes(); ?>>
 	<?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', 'block-development-examples' ); ?>
 </p>
-```
+```

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

@@ -30,7 +30,8 @@ This file contains the [metadata of the block](https://developer.wordpress.org/b
 
 Among other data it provides properties to define the paths of the files involved in the block's behaviour, output and style. If there's a build process involved, this `block.json` along with the generated files are placed into a destination folder (usually the `build` folder) so the paths provided target to the bundled versions of these files.
 
-The most relevant properties that can be defined in a `block.json` to set the files involved in the block's behaviour, output or style are:
+The most relevant properties that can be defined in a `block.json` to set the files involved in the block's behaviour, output, or style are:
+
 - The [`editorScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-script) property, usually set with the path of a bundled `index.js` file (output build from `src/index.js`).
 - The [`style`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style) property, usually set with the path of a bundled `style-index.css` file (output build from `src/style.(css|scss|sass)`).
 - The [`editorStyle`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-style) property, usually set with the path of a bundled `index.css` (output build from `src/editor.(css|scss|sass)`).

docs/getting-started/fundamentals/markup-representation-block.md

@@ -1,8 +1,9 @@
 # Markup representation of a block
 
-When stored, in the database (DB) or in templates as HTML files, blocks are represented using a [specific HTML grammar](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes), which is technically valid HTML based on HTML comments that act as explicit block delimiters 
+When stored in the database or in templates as HTML files, blocks are represented using a [specific HTML grammar](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes), which is technically valid HTML based on HTML comments that act as explicit block delimiters 
 
 These are some of the rules for the markup used to represent a block:
+
 - All core block comments start with a prefix and the block name: `wp:blockname`
 - For custom blocks, `blockname` is `namespace/blockname`
 - The comment can be a single line, self-closing, or wrapper for HTML content.
@@ -17,21 +18,22 @@ _Example: Markup representation of an `image` core block_
 ```
 
 The [markup representation of a block is parsed for the Block Editor](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/) and the block's output for the front end:
+
 - In the editor, WordPress parses this block markup, captures its data and loads its `edit` version
 - In the front end, WordPress parses this block markup, captures its data and generates its final HTML markup
 
 Whenever a block is saved, the `save` function, defined when the [block is registered in the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), is called to return the markup that will be saved into the database within the block delimiter's comment. If `save` is `null` (common case for blocks with dynamic rendering), only a single line block delimiter's comment is stored, along with any attributes
 
 The Post Editor checks that the markup created by the `save` function is identical to the block's markup saved to the database:
+
 - If there are any differences, the Post Editor triggers a [block validation error](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation).
 - Block validation errors usually happen when a block’s `save` function is updated to change the markup produced by the block.
 - A block developer can mitigate these issues by adding a [**block deprecation**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) to register the change in the block.
 
-The markup of a **block with dynamic rendering** is expected to change so the markup of these blocks is not saved to the database. What is saved in the DB as representation of the block, for blocks with dynamic rendering, is a single line of HTML consisting on just the block delimiter's comment (including block attributes values). That HTML is not subject to the Post Editor’s validation.
+The markup of a **block with dynamic rendering** is expected to change so the markup of these blocks is not saved to the database. What is saved in the database as representation of the block, for blocks with dynamic rendering, is a single line of HTML consisting on just the block delimiter's comment (including block attributes values). That HTML is not subject to the Post Editor’s validation.
 
 _Example: Markup representation of a block with dynamic rendering (`save` = `null`) and attributes_
 
-
 ```html
 <!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->
 ```

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

@@ -69,6 +69,7 @@ The content of <code>block.json</code> (or any other <code>.json</code> file) ca
 </div>
 
 The client-side block settings object passed as a second parameter includes two especially relevant properties:
+
 - `edit`: The React component that gets used in the editor for our block.
 - `save`: The function that returns the static HTML markup that gets saved to the Database.