diff --git a/docs/getting-started/fundamentals/README.md b/docs/getting-started/fundamentals/README.md
index 42dbace9d7ba3f..70f76c98c8ecf7 100644
--- a/docs/getting-started/fundamentals/README.md
+++ b/docs/getting-started/fundamentals/README.md
@@ -10,3 +10,4 @@ This section provides an introduction to the most relevant concepts in block dev
1. **[Markup representation of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block):** How blocks are represented in the database, theme templates, and patterns.
1. **[Static or Dynamic rendering of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering):** How blocks generate their front-end output either dynamically or statically.
1. **[JavaScript in the Block Editor](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor):** How to work with modern JavaScript when developing for the Block Editor.
+1. **[Lifecycle of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/lifecycle-of-block):** Understanding the different phases a block goes through and its various format transformations during its lifecycle.
diff --git a/docs/getting-started/fundamentals/lifecycle-of-block.md b/docs/getting-started/fundamentals/lifecycle-of-block.md
new file mode 100644
index 00000000000000..e768b0e6fa7648
--- /dev/null
+++ b/docs/getting-started/fundamentals/lifecycle-of-block.md
@@ -0,0 +1,172 @@
+# Lifecycle of a block
+
+A WordPress block goes through several distinct phases during its lifecycle, from registration to rendering. Understanding these phases is crucial for block development.
+
+## Overview of block lifecycle phases
+
+1. Registration phase
+2. Edit phase (Block Editor)
+3. Save phase
+4. Serialization phase
+5. Rendering phase
+
+### 1. Registration phase
+
+When WordPress loads, blocks go through a registration process:
+
+```js
+// Client-side registration
+registerBlockType('namespace/block-name', {
+ // Block configuration
+});
+
+// Server-side registration
+register_block_type('namespace/block-name', array(
+ // Block configuration
+));
+```
+
+During registration:
+- Block metadata from `block.json` is loaded
+- Block assets are enqueued
+- Server-side and client-side handlers are registered
+- Block variations and styles are registered
+
+### 2. Edit phase
+
+The edit phase occurs within the Block Editor when users interact with the block:
+
+- Block is instantiated as a React component
+- Block attributes are initialized with default or saved values
+- Edit function renders the block's interface
+- Block controls and inspector panels become available
+- Changes are stored in the block's attributes
+
+*Example: Block edit lifecycle*
+```js
+edit: ({ attributes, setAttributes, isSelected }) => {
+ // Component mount
+ useEffect(() => {
+ // Initialize block
+ }, []);
+
+ // User interactions
+ const onChangeContent = (newContent) => {
+ setAttributes({ content: newContent });
+ };
+
+ // Render block interface
+ return (
+
+ {/* Block content and controls */}
+
+ );
+}
+```
+
+### 3. Save phase
+
+The save phase occurs when the post is saved:
+
+- Block's save function is called
+- Current attributes are used to generate block markup
+- For dynamic blocks (`save: null`), only the block comment is saved
+
+*Example: Block save function*
+```js
+save: ({ attributes }) => {
+ return (
+
+ {/* Static markup generated from attributes */}
+
+ );
+}
+```
+
+### 4. Serialization phase
+
+During serialization, blocks are converted to their HTML storage format:
+
+```html
+
+
+ Block content
+
+
+```
+
+Key aspects of serialization:
+- Attributes are stored as JSON in the block comment
+- Block markup is validated against the save function output
+- Changes in markup structure require block deprecation handling
+
+### 5. Rendering phase
+
+The final phase where blocks are displayed on the frontend:
+
+For static blocks:
+- Saved markup is retrieved from the database
+- Markup is filtered through `render_block` filters
+- Final HTML is output to the page
+
+For dynamic blocks:
+- Block attributes are passed to the render callback
+- Server-side function generates fresh markup
+- Generated HTML is filtered and displayed
+
+*Example: Dynamic block render callback*
+```php
+function render_callback($attributes, $content) {
+ $wrapper_attributes = get_block_wrapper_attributes();
+
+ return sprintf(
+ '%2$s
',
+ $wrapper_attributes,
+ esc_html($attributes['content'])
+ );
+}
+```
+
+## Block format transformations
+
+Throughout its lifecycle, a block exists in different formats:
+
+1. **JavaScript object format**
+ - Used during registration and in the editor
+ - Contains all block configuration and attributes
+
+2. **React component format**
+ - Active in the Block Editor
+ - Handles user interactions and UI rendering
+
+3. **HTML comment format**
+ - Storage format in the database
+ - Contains block name and attributes
+
+4. **HTML markup format**
+ - Final rendered output
+ - Either stored (static) or generated (dynamic)
+
+## Best practices
+
+1. **Validation**
+ - Always validate data during format transformations
+ - Handle deprecated block versions gracefully
+ - Implement proper error handling
+
+2. **Performance**
+ - Minimize unnecessary re-renders in the edit function
+ - Use memoization for expensive computations
+ - Implement proper cleanup in useEffect hooks
+
+3. **Compatibility**
+ - Test block migrations thoroughly
+ - Maintain backward compatibility
+ - Follow WordPress coding standards
+
+## Additional Resources
+
+- [Block API Reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/)
+- [Data Flow in the Block Editor](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/)
+- [Block Deprecation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/)
+- [Block Validation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)
diff --git a/docs/manifest.json b/docs/manifest.json
index 8f267e79ef4feb..4efa8a4f011529 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -107,6 +107,12 @@
"markdown_source": "../docs/getting-started/fundamentals/javascript-in-the-block-editor.md",
"parent": "fundamentals"
},
+ {
+ "title": "Lifecycle of a block",
+ "slug": "lifecycle-of-block",
+ "markdown_source": "../docs/getting-started/fundamentals/lifecycle-of-block.md",
+ "parent": "fundamentals"
+ },
{
"title": "Glossary",
"slug": "glossary",
diff --git a/docs/toc.json b/docs/toc.json
index 69fe86a08256b6..b2f69cdd83edb5 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -47,6 +47,9 @@
},
{
"docs/getting-started/fundamentals/javascript-in-the-block-editor.md": []
+ },
+ {
+ "docs/getting-started/fundamentals/lifecycle-of-block.md": []
}
]
},