Docs: Put more structure to Architecture page

docs/explanations/architecture/README.md

@@ -2,12 +2,16 @@
 
 Let’s look at the big picture and the architectural and UX principles of the block editor and the Gutenberg repository.
 
--   [Key Concepts](/docs/explanations/architecture/key-concepts.md)
--   [Data Format And Data Flow](/docs/explanations/architecture/data-flow.md)
--   [Understand the repository folder structure](/docs/contributors/folder-structure.md).
+## Editor
+
+-   [Key concepts](/docs/explanations/architecture/key-concepts.md).
+-   [Data format and data flow](/docs/explanations/architecture/data-flow.md).
+-   [Site editing templates](/docs/explanations/architecture/full-site-editing-templates.md).
+-   [Styles in the editor](/docs/explanations/architecture/styles.md).
+-   [Performance](/docs/explanations/architecture/performance.md).
+
+## Gutenberg Repository
+
 -   [Modularity and WordPress Packages](/docs/explanations/architecture/modularity.md).
--   [Block Editor Performance](/docs/explanations/architecture/performance.md).
--   What are the decision decisions behind the Data Module?
--   [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/explanations/architecture/automated-testing.md)
--   [What's the difference between the different editor packages? What's the purpose of each package?](/docs/explanations/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package)
--   [Template and template parts flows](/docs/explanations/architecture/full-site-editing-templates.md)
+-   [Understand the repository folder structure](/docs/contributors/folder-structure.md).
+-   **Outdated!** [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/explanations/architecture/automated-testing.md).

docs/explanations/architecture/full-site-editing-templates.md

@@ -1,4 +1,4 @@
-# Full Site Editing Templates
+# Site Editing Templates
 
 ## Template and template part flows
 

docs/explanations/architecture/key-concepts.md

@@ -26,11 +26,13 @@ Blocks can be static or dynamic. Static blocks contain rendered content and an o
 
 Each block contains Attributes or configuration settings, which can be sourced from raw HTML in the content via meta or other customizable origins.
 
-### Transformations
+More on [Data format and data flow](/docs/explanations/architecture/data-flow.md).
 
-Blocks have the ability to be transformed into other block types. This allows basic operations like converting a paragraph into a heading, but also more intricate ones like multiple images becoming a gallery. Transformations work for single blocks and for multi-block selections. Internal block variations are also possible transformation targets.
+### Block Transforms
 
-### Variations
+Blocks have the ability to be transformed into other block types. This allows basic operations like converting a paragraph into a heading, but also more intricate ones like multiple images becoming a gallery. Block transforms work for single blocks and for multi-block selections. Internal block variations are also possible transformation targets.
+
+### Block Variations
 
 Given a block type, a block variation is a predefined set of its initial attributes. This API allows creating a single block from which multiple configurations are possible. Variations provide different possible interfaces, including showing up as entirely new blocks in the library, or as presets when inserting a new block. Read [the API documentation](/docs/reference-guides/block-api/block-registration.md#variations-optional) for more details.
 
@@ -41,24 +43,28 @@ Given a block type, a block variation is a predefined set of its initial attribu
 
 ## Reusable Blocks
 
-A reusable blocks is a block (or multiple blocks) that can be inserted and edited globally at once. If a reusable block is edited in one place, those changes are reflected across all posts and pages that block is used. Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page.
+A reusable blocks is **an instance** of a block (or multiple blocks) that can be inserted and edited in multiples places, remaining in sync everywhere. If a reusable block is edited in one place, those changes are reflected across all posts and pages that block is used. Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page.
 
 Any edits to a reusable block will appear on every other use of that block, saving time from having to make the same edit on different posts.
 
-In technical details, reusable blocks are stored as a hidden post type (`wp_block`) and are dynamic blocks that "ref" or reference the `post_id` and return the `post_content` for that block.
+Internally, reusable blocks are stored as a hidden post type (`wp_block`) and are dynamic blocks that "ref" or reference the `post_id` and return the `post_content` for that block.
 
 ## Patterns
 
-A [block pattern](/docs/reference-guides/block-api/block-patterns.md) is a group of blocks that have been combined together creating a design pattern. These design patterns provide a starting point for building more advanced pages and layouts quickly. A block pattern can be as small as a single block or as large as a full page of content. Unlike reusable blocks, once a pattern is inserted it doesn't remain in sync with the original content as the blocks contained are meant to be edited and customized by the user. Underneath the surface, patterns are just regular blocks composed together. Themes can register patterns to offer users quick starting points with a design language familiar to that theme's aesthetics.
+A [block pattern](/docs/reference-guides/block-api/block-patterns.md) is a group of blocks that have been combined together creating a design pattern. These design patterns provide a starting point for building more advanced pages and layouts quickly, instead of inserting individual blocks. A block pattern can be as small as a single block or as large as a full page of content. Unlike reusable blocks, once a pattern is inserted it doesn't remain in sync with the original content as the blocks contained are meant to be edited and customized by the user. Underneath the surface, patterns are just regular blocks composed together. Themes can register patterns to offer users quick starting points with a design language familiar to that theme's aesthetics.
+
+## Templates
 
-## Templates (in progress)
+While the post editor concentrates on the content of a post, the [template](/docs/reference-guides/block-api/block-templates.md) editor allows declaring and editing an entire site using blocks, from header to footer. Templates are broken down between templates (that describe a full page) and template parts (that describe reusable areas within a template, including semantic areas like header, sidebar, and footer).
 
-While the post editor concentrates on the content of a post, the [template](/docs/reference-guides/block-api/block-templates.md) editor allows declaring and editing an entire site using blocks, from header to footer. To support these efforts there's a collection of blocks that interact with different parts of a site (like the site title, description, logo, navigation, etc) as well as semantic areas like header, sidebar, and footer. Templates are broken down between templates (that describe a full page) and template parts (that describe reusable areas within a template). These templates and template parts can be composed together and registered by a theme. They are also entirely editable by users using the block editor. Customized templates are saved in a `wp_template` post type. Block templates include both static pages and dynamic ones, like archives, singular, home, 404, etc.
+These templates and template parts can be composed together and registered by a theme. They are also entirely editable by users using the block editor; a collection of blocks that interact with different properties and settings of the site (like the site title, description, logo, navigation, etc) are especially useful when editing templates and template parts. Customized templates are saved in a `wp_template` post type. Block templates include both static pages and dynamic ones, like archives, singular, home, 404, etc.
 
 Note: custom post types can also be initialized with a starting `post_content` template that should not be confused with the theme template system described above.
 
-## Global Styles
+More on [Site editing templates](/docs/explanations/architecture/full-site-editing-templates.md).
+
+## Styles
 
-Global Styles is both an interface (which users access through the site editor) and a configuration system done through [a `theme.json` file](/docs/how-to-guides/themes/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what specific tools a theme offers (like a custom color palette), the available design tools present, and an infrastructure that allows to coordinate the styles coming from WordPress, the active theme, and the user.
+Styles, formerly known as Global Styles and as such referenced in the code, is both an interface that users access through the editor and a configuration system done through [a `theme.json` file](/docs/how-to-guides/themes/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what specific tools a theme offers (like a custom color palette), the available design tools present, and an infrastructure that allows to coordinate the styles coming from WordPress, the active theme, and the user.
 
 Learn more about [Global Styles](/docs/explanations/architecture/styles.md#global-styles).

docs/explanations/architecture/styles.md

@@ -1,23 +1,28 @@
-## Styles in the block editor
+## Styles in the editor
 
 This document introduces the main concepts related to styles that affect the user content in the block editor. It points to the relevant reference guides and tutorials for readers to dig deeper into each one of the ideas presented. It's aimed to block authors and people working in the block editor project.
 
 1. [HTML and CSS](#html-and-css)
 2. [Block styles](#block-styles)
-  - [From UI controls to HTML markup](#from-ui-controls-to-html-markup)
-  - [Block Supports API](#block-supports-api)
-  - [Current limitations of the Block Supports API](#current-limitations-of-the-block-supports-api)
+
+-   [From UI controls to HTML markup](#from-ui-controls-to-html-markup)
+-   [Block Supports API](#block-supports-api)
+-   [Current limitations of the Block Supports API](#current-limitations-of-the-block-supports-api)
+
 3. [Global styles](#global-styles)
-  - [Gather data](#gather-data)
-  - [Consolidate data](#consolidate-data)
-  - [From data to styles](#from-data-to-styles)
-  - [Current limitations of the Global Styles API](#current-limitations-of-the-global-styles-api)
+
+-   [Gather data](#gather-data)
+-   [Consolidate data](#consolidate-data)
+-   [From data to styles](#from-data-to-styles)
+-   [Current limitations of the Global Styles API](#current-limitations-of-the-global-styles-api)
+
 4. [Layout styles](#layout-styles)
-  - [Base layout styles](#base-layout-styles)
-  - [Individual layout styles](#individual-layout-styles)
-  - [Available layout types](#available-layout-types)
-  - [Targeting layout or container blocks from themes](#targeting-layout-or-container-blocks-from-themes)
-  - [Opting out of generated layout styles](#opting-out-of-generated-layout-styles)
+
+-   [Base layout styles](#base-layout-styles)
+-   [Individual layout styles](#individual-layout-styles)
+-   [Available layout types](#available-layout-types)
+-   [Targeting layout or container blocks from themes](#targeting-layout-or-container-blocks-from-themes)
+-   [Opting out of generated layout styles](#opting-out-of-generated-layout-styles)
 
 ### HTML and CSS
 
@@ -524,16 +529,16 @@ Common layout definitions are stored in [the core `theme.json` file](https://git
 
 When a block that opts in to the experimental layout support is rendered, two things are processed and added to the output via [`layout.php`](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/layout.php):
 
-- Semantic class names are added to the block markup to indicate which layout settings are in use. For example, `is-layout-flow` is for blocks (such as Group) that use the default/flow layout, and `is-content-justification-right` is added when a user sets a block to use right justification.
-- Individual styles are generated for non-default layout values that are set on the individual block being rendered. These styles are attached to the block via a container class name using the form `wp-container-$id` where the `$id` is a [unique number](https://developer.wordpress.org/reference/functions/wp_unique_id/).
+-   Semantic class names are added to the block markup to indicate which layout settings are in use. For example, `is-layout-flow` is for blocks (such as Group) that use the default/flow layout, and `is-content-justification-right` is added when a user sets a block to use right justification.
+-   Individual styles are generated for non-default layout values that are set on the individual block being rendered. These styles are attached to the block via a container class name using the form `wp-container-$id` where the `$id` is a [unique number](https://developer.wordpress.org/reference/functions/wp_unique_id/).
 
 #### Available layout types
 
 There are currently three layout types in use:
 
-* Default/Flow: Items are stacked vertically. The parent container block is set to `display: flow` and the spacing between children is handled via vertical margins.
-* Constrained: Items are stacked vertically, using the same spacing logic as the Flow layout. Features constrained widths for child content, outputting widths for standard content size and wide size. Defaults to using global `contentSize` and `wideSize` values set in `settings.layout` in the `theme.json`.
-* Flex: Items are displayed using a Flexbox layout. Defaults to a horizontal orientation. Spacing between children is handled via the `gap` CSS property.
+-   Default/Flow: Items are stacked vertically. The parent container block is set to `display: flow` and the spacing between children is handled via vertical margins.
+-   Constrained: Items are stacked vertically, using the same spacing logic as the Flow layout. Features constrained widths for child content, outputting widths for standard content size and wide size. Defaults to using global `contentSize` and `wideSize` values set in `settings.layout` in the `theme.json`.
+-   Flex: Items are displayed using a Flexbox layout. Defaults to a horizontal orientation. Spacing between children is handled via the `gap` CSS property.
 
 For controlling spacing between blocks, and enabling block spacing controls see: [What is blockGap and how can I use it?](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#what-is-blockgap-and-how-can-i-use-it).
 
@@ -551,17 +556,17 @@ Work is currently underway to expand stable semantic classnames in Layout block
 
 The current semantic class names that can be output by the Layout block support are:
 
-* `is-layout-flow`: Blocks that use the Default/Flow layout type.
-* `is-layout-constrained`: Blocks that use the Constrained layout type.
-* `is-layout-flex`: Blocks that use the Flex layout type.
-* `wp-container-$id`: Where `$id` is a semi-random number. A container class that only exists when the block contains non-default Layout values. This class should not be used directly for any CSS targeting as it may or may not be present.
-* `is-horizontal`: When a block explicitly sets `orientation` to `horizontal`.
-* `is-vertical`: When a block explicitly sets `orientation` to `vertical`.
-* `is-content-justification-left`: When a block explicitly sets `justifyContent` to `left`.
-* `is-content-justification-center`: When a block explicitly sets `justifyContent` to `center`.
-* `is-content-justification-right`: When a block explicitly sets `justifyContent` to `right`.
-* `is-content-justification-space-between`: When a block explicitly sets `justifyContent` to `space-between`.
-* `is-nowrap`: When a block explicitly sets `flexWrap` to `nowrap`.
+-   `is-layout-flow`: Blocks that use the Default/Flow layout type.
+-   `is-layout-constrained`: Blocks that use the Constrained layout type.
+-   `is-layout-flex`: Blocks that use the Flex layout type.
+-   `wp-container-$id`: Where `$id` is a semi-random number. A container class that only exists when the block contains non-default Layout values. This class should not be used directly for any CSS targeting as it may or may not be present.
+-   `is-horizontal`: When a block explicitly sets `orientation` to `horizontal`.
+-   `is-vertical`: When a block explicitly sets `orientation` to `vertical`.
+-   `is-content-justification-left`: When a block explicitly sets `justifyContent` to `left`.
+-   `is-content-justification-center`: When a block explicitly sets `justifyContent` to `center`.
+-   `is-content-justification-right`: When a block explicitly sets `justifyContent` to `right`.
+-   `is-content-justification-space-between`: When a block explicitly sets `justifyContent` to `space-between`.
+-   `is-nowrap`: When a block explicitly sets `flexWrap` to `nowrap`.
 
 #### Opting out of generated layout styles