Docs: Create a Full Site Editing overview document

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

@@ -0,0 +1,52 @@
+# 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. 
+
+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) 
+- 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.
+
+- 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.
+
+- 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.
+
+```
+❯ git clone https://github.com/WordPress/theme-experiments
+❯ cd theme-experiments
+❯ php new-empty-theme.php
+Please provide the following information:
+Theme name: TestTheme
+Description: A theme to test
+Author: Marcus Kazmierczak
+Theme URI: https://github.com/mkaz
+
+Your new theme is ready!
+```
+
+You can then copy the generated directory to your `wp-content/themes` directory and start playing with the Site Editor to build and extend the theme.
+
+### 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.
+
+### 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/).

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

@@ -1,36 +1,31 @@
-# Creating a block-based theme
+# Create a block theme
 
-The purpose of this tutorial is to show how to create a basic block based theme
-and help theme developers transition to full site editing.
+The purpose of this tutorial is to show how to create a block theme and help theme developers transition to full site editing.
 
-You will learn about the required files, how to combine templates and template parts,
-how to add presets for global styles, and how to add blocks and export the templates in the site editor.
+You will learn about the required files, how to combine templates and template parts, how to add presets for global styles, and how to add blocks and export the templates in the site editor.
 
 Full site editing is an experimental feature and the workflow in this tutorial is likely to change.
 
 This tutorial is up to date as of Gutenberg version 9.1.
 
 ## Table of Contents
 
-1.  [What is needed to create a block-based theme?](/docs/how-to-guides/block-based-themes/README.md#what-is-needed-to-create-a-block-based-theme)
-2.  [Creating the theme](/docs/how-to-guides/block-based-themes/README.md#creating-the-theme)
-3.  [Creating the templates and template parts](/docs/how-to-guides/block-based-themes/README.md#creating-the-templates-and-template-parts)
-4.  [experimental-theme.json - Global styles](/docs/how-to-guides/block-based-themes/README.md#experimental-theme-json-global-styles)
-5.  [Adding blocks](/docs/how-to-guides/block-based-themes/block-based-themes-2-adding-blocks.md)
+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)
 
-## What is needed to create a block-based theme?
+## What is needed to create a block theme?
 
-To use a block based theme you need to have Gutenberg installed and full site editing must be enabled.
+To use a block theme you need to use the Gutenberg plugin.
 
-Full site editing can be enabled from the Gutenberg experiments menu in the WordPress admin area.
-
-A block-based 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.
+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.
 
 ### Required files and file structure
 
-A block based theme requires an `index.php` file, an index template file, a `style.css` file, and a `functions.php` file.
+A block theme requires an `index.php` file, an index template file, a `style.css` file, and a `functions.php` file.
 
 The theme may optionally include an [experimental-theme.json file](/docs/how-to-guides/themes/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme.
 
@@ -380,4 +375,3 @@ Below are the presets and styles combined:
 }
 ```
 
-## [Adding blocks](/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md)

docs/manifest.json

@@ -71,6 +71,12 @@
 		"markdown_source": "../docs/getting-started/tutorials/create-block/submitting-to-block-directory.md",
 		"parent": "create-block"
 	},
+	{
+		"title": "Full Site Editing",
+		"slug": "full-site-editing",
+		"markdown_source": "../docs/getting-started/full-site-editing.md",
+		"parent": "handbook"
+	},
 	{
 		"title": "Glossary",
 		"slug": "glossary",
@@ -312,17 +318,11 @@
 		"parent": "themes"
 	},
 	{
-		"title": "Creating a block-based theme",
-		"slug": "block-based-theme",
-		"markdown_source": "../docs/how-to-guides/block-based-theme/README.md",
+		"title": "Create a block theme",
+		"slug": "block-theme",
+		"markdown_source": "../docs/how-to-guides/block-theme/README.md",
 		"parent": "how-to-guides"
 	},
-	{
-		"title": "Adding blocks to your theme",
-		"slug": "block-based-themes-2-adding-blocks",
-		"markdown_source": "../docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md",
-		"parent": "block-based-theme"
-	},
 	{
 		"title": "Backward Compatibility",
 		"slug": "backward-compatibility",

docs/toc.json

@@ -37,6 +37,7 @@
 					}
 				]
 			},
+			{ "docs/getting-started/full-site-editing.md": [] },
 			{ "docs/getting-started/glossary.md": [] },
 			{ "docs/getting-started/faq.md": [] },
 			{ "docs/getting-started/history.md": [] },
@@ -135,13 +136,7 @@
 					{ "docs/how-to-guides/themes/theme-json.md": [] }
 				]
 			},
-			{
-				"docs/how-to-guides/block-based-theme/README.md": [
-					{
-						"docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md": []
-					}
-				]
-			},
+			{ "docs/how-to-guides/block-theme/README.md": [] },
 			{
 				"docs/how-to-guides/backward-compatibility/README.md": [
 					{