Docs: Organize and update block theme docs (#31167)

* Organize block theme docs together, improve heading and links

* Fix links to moved docs

* Typo and link fix

* Reorganize around themes/ dir instead of block-theme/

* Update links to the themes/ dir

* Update couple more uses of block-based theme

* Formating spaces

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

@@ -2,13 +2,15 @@
 
 ## Template and template part flows
 
-> This is the documentation for the current implementation of the block-based templates and template parts themes. This is part of the Full Site Editing project. These features are still experimental in the plugin. “Experimental” means this is just an early implementation that is subject to potential drastic and breaking changes in iterations based on feedback from users, contributors, and theme authors.
+<div class="callout callout-alert">
+This is the documentation for the current implementation of the block templates and template parts themes. This is part of the Full Site Editing project. These features are still experimental in the plugin. “Experimental” means this is just an early implementation that is subject to potential drastic and breaking changes in iterations based on feedback from users, contributors, and theme authors.
+</div>
 
-This document will explain the internals of how templates and templates parts are rendered in the frontend and edited in the backend. For an introduction about block-based themes and Full site editing templates, refer to the [block-based themes documentation](/docs/how-to-guides/themes/block-based-themes.md).
+This document will explain the internals of how templates and templates parts are rendered in the frontend and edited in the backend. For an introduction about block themes and Full site editing templates, refer to the [block theme documentation](/docs/how-to-guides/themes/block-theme-overview.md).
 
 ## Storage
 
-Just like the regular templates, the block-based templates live initially as files in the theme folder but the main difference is that the user can edit these templates in the UI in the Site Editor.
+Just like the regular templates, the block templates live initially as files in the theme folder but the main difference is that the user can edit these templates in the UI in the Site Editor.
 
 When a user edits a template (or template-part), the initial theme template file is kept as is but a forked version of the template is saved to the `wp_template` custom post type (or `wp_template_part` for template parts).
 
@@ -30,11 +32,11 @@ The synchronization is important for two different flows:
 
 -   When editing the template and template parts, the site editor frontend fetches the edited and available templates through the REST API. This means that for all `GET` API requests performed to the `wp-templates` and `wp-template-parts` endpoint synchronization is required.
 -   When rendering a template (sometimes referred to as "resolving a template"): this is the algorithm that WordPress follows to traverse the template hierarchy and find the right template to render for the current page being loaded.
--   When exporting a block-based theme, we need to export all its templates back as files. The synchronization is required to simplify the operation and only export the CPT templates.
+-   When exporting a block theme, we need to export all its templates back as files. The synchronization is required to simplify the operation and only export the CPT templates.
 
 ## Switching themes
 
-Since block-based themes make use of templates that can refer to each other and that can be saved to a custom post type, it becomes possible to mix templates and template parts from different themes. For example:
+Since block themes make use of templates that can refer to each other and that can be saved to a custom post type, it becomes possible to mix templates and template parts from different themes. For example:
 
 -   A user might like the "header" template part of theme A and would like to use it in theme B.
 -   A user might like the "contact" template from theme A and would like to use it in theme B.

docs/getting-started/faq.md

@@ -320,7 +320,7 @@ Blocks are able to provide base structural CSS styles, and themes can add styles
 
 Other features, like the new _wide_ and _full-wide_ alignment options, are simply CSS classes applied to blocks that offer this alignment. We are looking at how a theme can opt in to this feature, for example using `add_theme_support`.
 
-This is currently a work in progress and we recommend reviewing the [block based theme documentation](/docs/how-to-guides/block-based-theme/README.md) to learn more.
+This is currently a work in progress and we recommend reviewing the [block based theme documentation](/docs/how-to-guides/themes/block-theme-overview.md) to learn more.
 
 ## What are block variations? Are they the same as block styles?
 

docs/getting-started/full-site-editing.md

@@ -1,30 +1,30 @@
 # Full Site Editing
 
-At the highest level, the vision of Full Site Editing is to provide a collection of features that bring the familiar experience and extendability of blocks to all parts of your site rather than just post and pages. You can think of Full Site Editing as the umbrella project name for various sub-projects within Gutenberg that make this vision possible. Projects under Full Site Editing (FSE) include the Site Editor, Global Styles, numerous Site/Post/Page specific blocks, Query block, Navigation block, Templates, and block themes. 
+At the highest level, the vision of Full Site Editing is to provide a collection of features that bring the familiar experience and extendability of blocks to all parts of your site rather than just post and pages. You can think of Full Site Editing as the umbrella project name for various sub-projects within Gutenberg that make this vision possible. Projects under Full Site Editing (FSE) include the Site Editor, Global Styles, numerous Site/Post/Page specific blocks, Query block, Navigation block, Templates, and block themes.
 
-There are other projects, like the Navigation Editor and Widget Editor, that are meant to specifically help classic themes begin adapting more to the block framework and to act as a stepping stone of sorts to Full Site Editing. These are separate projects from Full Site Editing though but are worth being aware of as they ultimately help the cause of getting more people adjusted to using blocks in more places. 
- 
-**Jump in:** 
+There are other projects, like the Navigation Editor and Widget Editor, that are meant to specifically help classic themes begin adapting more to the block framework and to act as a stepping stone of sorts to Full Site Editing. These are separate projects from Full Site Editing though but are worth being aware of as they ultimately help the cause of getting more people adjusted to using blocks in more places.
+
+**Jump in:**
 
 The best way to learn something is start playing with it. So jump in by installing the Gutenberg plugin from the plugins directory and activating a block theme on a test site. We recommend the [TT1 Blocks theme](https://wordpress.org/themes/tt1-blocks/), it is listed in the theme diretory and our development reference theme. You can find other themes in the directory using the [full-site-editing feature tag](https://wordpress.org/themes/tags/full-site-editing/).
 
 ## Get Involved
 
 An ongoing [FSE Outreach program](https://make.wordpress.org/test/handbook/full-site-editing-outreach-experiment/) is in place with calls for testing and is a great way to get involved and learn about the new features.
 
-- Join in on [WordPress Slack](https://make.wordpress.org/chat/) at [#fse-outreach-experiment](https://wordpress.slack.com/archives/C015GUFFC00) 
+- Join in on [WordPress Slack](https://make.wordpress.org/chat/) at [#fse-outreach-experiment](https://wordpress.slack.com/archives/C015GUFFC00)
 - Participate in the [Calls for Testing](https://make.wordpress.org/test/tag/fse-testing-call/) by testing and giving feedback.
 - See detailed [How to Test FSE instructions](https://make.wordpress.org/test/handbook/full-site-editing-outreach-experiment/how-to-test-fse/) to get setup to test FSE features.
 
 ## Block Themes
 
-If you are using the Gutenberg plugin you can run, test, and develop block themes. Block themes are themes built using templates composed using blocks. See [block theme overview](/docs/how-to-guides/themes/block-based-themes.md) for additional details.
+If you are using the Gutenberg plugin you can run, test, and develop block themes. Block themes are themes built using templates composed using blocks. See [block theme overview](/docs/how-to-guides/themes/block-theme-overview.md) for additional details.
 
-- See the [Create a Block Theme](/docs/how-to-guides/block-theme/README.md) tutorial for a walk-through of the pieces of a block theme.
+- See the [Create a Block Theme](/docs/how-to-guides/themes/create-block-theme.md) tutorial for a walk-through of the pieces of a block theme.
 
 - For examples, see the [WordPress/theme-experiments](https://github.com/WordPress/theme-experiments/) repository with several block themes there including the source for the above mentioned TT1 Blocks.
 
-- Use the `empty-theme.php` script from theme-experiments repo to generate a start block theme, it will prompt you with a few questions and create a theme.
+- Use the `empty-theme.php` script from theme-experiments repo to generate a starter block theme, it will prompt you with a few questions and create a theme.
 
 ```
 ❯ git clone https://github.com/WordPress/theme-experiments
@@ -43,10 +43,10 @@ You can then copy the generated directory to your `wp-content/themes` directory
 
 ### Template and Template Parts
 
-See the [architecture document on templates](docs/explanations/architecture/full-site-editing-templates.md) for an explanation on the internals of how templates and templates parts are rendered in the frontend and edited in the backend.
+See the [architecture document on templates](/docs/explanations/architecture/full-site-editing-templates.md) for an explanation on the internals of how templates and templates parts are rendered in the frontend and edited in the backend.
 
 ### theme.json
 
 Instead of the proliferation of theme support flags or alternative methods, a new `theme.json` file is being used to define theme settings. **NOTE:** This feature is still experimental and changing, so the interim file name is `experimental-theme.json`
 
-See [documentation for theme.json](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/).
+See [documentation for theme.json](/docs/how-to-guides/themes/theme-json.md).

docs/getting-started/glossary.md

@@ -11,7 +11,7 @@
 <dd>The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.</dd>
 
 <dt>Block Based Theme</dt>
-<dd>A theme built in block forward way that allows Full Site Editing to work. The core of a block-based theme are its block templates and block template parts. To date, block-based theme templates have been HTML files of block markup that map to templates from the standard WordPress template hierarchy. </dd>
+<dd>A theme built in block forward way that allows Full Site Editing to work. The core of a block theme are its block templates and block template parts. To date, block theme templates have been HTML files of block markup that map to templates from the standard WordPress template hierarchy. </dd>
 
 <dt>Block categories</dt>
 <dd>These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Library.</dd>

docs/how-to-guides/themes/README.md

@@ -1,5 +1,10 @@
-# Theming for the Block Editor
+# Themes
 
-The new editor provides a number of options for theme designers and developers, including theme-defined color settings, font size control, and much more.
+The block editor provides a number of options for theme designers and developers, including theme-defined color settings, font size control, and much more.
 
-In this section, you'll learn about the ways that themes can customize the editor.
+**Contents**
+
+- [Block Theme Overview](/docs/how-to-guides/themes/block-theme-overview.md)
+- [Create a Block Theme](/docs/how-to-guides/themes/create-block-theme.md)
+- [Global Settings (theme.json)](/docs/how-to-guides/themes/theme-json.md)
+- [Theme Support](/docs/how-to-guides/themes/theme-support.md)

docs/how-to-guides/themes/block-based-themes.md → docs/how-to-guides/themes/block-theme-overview.md

@@ -1,18 +1,18 @@
-# Block-based Themes (Experimental)
+# Block Theme
 
-> This is the documentation for the current implementation of block-based themes, also known as Full Site Editing or Block Content Areas. These features are still experimental in the plugin. “Experimental” means this is just an early implementation that is subject to potential drastic and breaking changes in iterations based on feedback from users, contributors and theme authors.
+<div class="callout callout-alert">
+These features are still experimental in the plugin. “Experimental” means this is just an early implementation that is subject to potential drastic and breaking changes in iterations based on feedback from users, contributors and theme authors.
 
-> Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. You can provide feedback in the weekly #core-editor chats where the latest progress of this effort will be shared and discussed, or async via Github issues.
-
-**Note:** To use these features, activate a theme that includes a `block-templates/index.html` file. This will signal to the block editor that the theme should use full-site editing features.
+Documentation is shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. You can provide feedback in the weekly #core-editor chats, or #fse-outreach-experiment channels, or async via Github issues.
+</div>
 
-## What is a block-based theme?
+## What is a block theme?
 
-A block-based theme is a WordPress theme with templates entirely composed of blocks so that in addition to the post content of the different post types (pages, posts, ...), the block editor can also be used to edit all areas of the site: headers, footers, sidebars, etc.
+A block theme is a WordPress theme with templates entirely composed of blocks so that in addition to the post content of the different post types (pages, posts, ...), the block editor can also be used to edit all areas of the site: headers, footers, sidebars, etc.
 
-## What is the structure of a block-based theme?
+## What is the structure of a block theme?
 
-A very simple block-based theme is structured like so:
+A very simple block theme is structured like so:
 
 ```
 theme
@@ -96,7 +96,7 @@ Note that it won't take precedence over any of your theme's templates with highe
 
 ## Theme Blocks
 
-Some blocks have been made specifically for block-based themes. For example, you'll most likely use the **Site Title** block in your site's header while your **single** block template will most likely include a **Post Title** and a **Post Content** block.
+Some blocks have been made specifically for block themes. For example, you'll most likely use the **Site Title** block in your site's header while your **single** block template will most likely include a **Post Title** and a **Post Content** block.
 
 As we're still early in the process, the number of blocks specifically dedicated to these block templates is relatively small but more will be added as we move forward with the project. As of Gutenberg 8.5, the following blocks are currently available:
 
@@ -137,4 +137,4 @@ remove_theme_support( 'block-templates' );
 ## Resources
 
 -   [Full Site Editing](https://github.com/WordPress/gutenberg/labels/%5BFeature%5D%20Full%20Site%20Editing) label.
--   [Theme Experiments](https://github.com/WordPress/theme-experiments) repository, full of block-based theme examples created by the WordPress community.
+-   [Theme Experiments](https://github.com/WordPress/theme-experiments) repository, full of block theme examples created by the WordPress community.

docs/how-to-guides/block-theme/README.md → docs/how-to-guides/themes/create-block-theme.md

@@ -10,18 +10,18 @@ This tutorial is up to date as of Gutenberg version 9.1.
 
 ## Table of Contents
 
-1.  [What is needed to create a block-theme?](/docs/how-to-guides/block-theme/README.md#what-is-needed-to-create-a-block-theme)
-2.  [Creating the theme](/docs/how-to-guides/block-theme/README.md#creating-the-theme)
-3.  [Creating the templates and template parts](/docs/how-to-guides/block-theme/README.md#creating-the-templates-and-template-parts)
-4.  [experimental-theme.json - Global styles](/docs/how-to-guides/block-theme/README.md#experimental-theme-json-global-styles)
+1.  [What is needed to create a block-theme?](#what-is-needed-to-create-a-block-theme)
+2.  [Creating the theme](#creating-the-theme)
+3.  [Creating the templates and template parts](#creating-the-templates-and-template-parts)
+4.  [experimental-theme.json - Global styles](#experimental-theme-json-global-styles)
 
 ## What is needed to create a block theme?
 
 To use a block theme you need to use the Gutenberg plugin.
 
 A block theme is built using HTML templates and template parts. Templates are the main files used in the [template hierarchy](https://developer.wordpress.org/themes/basics/template-hierarchy/), for example index, single or archive. Templates can optionally include structural template parts, for example a header, footer or sidebar.
 
-Each template or template part contains the [block grammar](https://developer.wordpress.org/block-editor/principles/key-concepts/#blocks), the HTML, for the selected blocks. The block HTML is generated in and exported from the **site editor**. It can also be added to the theme's HTML files manually.
+Each template or template part contains the [block grammar](/docs/explanations/architecture/key-concepts/), the HTML, for the selected blocks. The block HTML is generated in and exported from the **site editor**. It can also be added to the theme's HTML files manually.
 
 ### Required files and file structure
 
@@ -85,7 +85,7 @@ _You no longer need to add theme support for the title tag. It is already enable
 
 https://developer.wordpress.org/themes/basics/theme-functions/#what-is-functions-php
 
-https://developer.wordpress.org/block-editor/developers/themes/theme-support/
+https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/
 
 ```php
 <?php
@@ -189,7 +189,7 @@ It is used to:
 -   Set global styles.
 -   Set styles for individual block types.
 
-[The documentation for global styles contains a list of available block and style combinations.](https://developer.wordpress.org/block-editor/developers/themes/theme-json/)
+[The documentation for global styles contains a list of available block and style combinations.](/docs/how-to-guides/themes/theme-json.md)
 
 Create a file called `experimental-theme.json` and save it inside the main folder.
 
@@ -282,7 +282,7 @@ Block styles are separate from global styles. Add the code after the globals, bu
 
 CSS variables for font sizes are generated using the `editor-font-sizes` theme support or by adding a global preset.
 
-https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes
+https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-font-sizes
 
 If the theme does not add any custom font sizes, variables are created using the default sizes.
 This example adds the default medium font size to the paragraph block.