Docs: Create a Full Site Editing overview document

Creates a new getting started document for full site editng. There are numerous sections and sub-projects for FSE, this document will gather together these resources and link off so people can find what they need. Closes #30637
WordPress · Apr 23, 2021 · f6864e4 · f6864e4
1 parent 4ab1a3a
commit f6864e4
Show file tree

Hide file tree

Showing 5 changed files with 66 additions and 25 deletions.
diff --git a/docs/getting-started/full-site-editing.md b/docs/getting-started/full-site-editing.md
@@ -0,0 +1,38 @@
+# Full Site Editing
+
+Full Site Editing is the umbrella project name for various sub-projects within Gutenberg. Projects under Full Site Editing (FSE) include the Site Editor, Widgets Editor, Navigation Editor, Global Styles, numerous Site/Post/Page specific blocks, Query block, Navigation block, Templates, and block themes.
+
+## Get Involved
+
+The majority of full site editing features are avilable in the Gutenberg plungin, and an ongoing [FSE Outreach program](https://make.wordpress.org/test/handbook/full-site-editing-outreach-experiment/) is running with calls for testing amongst a community of folks.
+
+- Join in on Slack at #fse-outreach-experiment
+- Participate in the [Calls for Testing](https://make.wordpress.org/test/tag/fse-testing-call/) and test and feedback.
+- See the [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 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.
+
+- If you want to dive right in, see the [github.com/WordPress/theme-experiments](https://github.com/WordPress/theme-experiments/) repository. You can download different example block themes there, try the [TT1 Blocks](https://github.com/WordPress/theme-experiments/tree/master/tt1-blocks) is a block theme recreating the TwentyTwentyOne default theme.
+
+- 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.
+
+
diff --git a/...how-to-guides/block-based-theme/README.md → docs/how-to-guides/block-theme/README.md b/...how-to-guides/block-based-theme/README.md → docs/how-to-guides/block-theme/README.md
@@ -1,36 +1,32 @@
-# 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)
+5.  [Adding blocks](/docs/how-to-guides/block-theme/block-theme-2-adding-blocks.md)
 
-## 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 +376,4 @@ Below are the presets and styles combined:
 }
 ```
 
-## [Adding blocks](/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md)
+Next: [Adding blocks](/docs/how-to-guides/block-theme/block-theme-2-adding-blocks.md)
diff --git a/...eme/block-based-themes-2-adding-blocks.md → ...lock-theme/block-theme-2-adding-blocks.md b/...eme/block-based-themes-2-adding-blocks.md → ...lock-theme/block-theme-2-adding-blocks.md
diff --git a/docs/manifest.json b/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,16 +318,16 @@
 		"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"
+		"slug": "block-theme-2-adding-blocks",
+		"markdown_source": "../docs/how-to-guides/block-theme/block-theme-2-adding-blocks.md",
+		"parent": "block-theme"
 	},
 	{
 		"title": "Backward Compatibility",

diff --git a/docs/toc.json b/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": [] },
@@ -136,9 +137,9 @@
 				]
 			},
 			{
-				"docs/how-to-guides/block-based-theme/README.md": [
+				"docs/how-to-guides/block-theme/README.md": [
 					{
-						"docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md": []
+						"docs/how-to-guides/block-theme/block-theme-2-adding-blocks.md": []
 					}
 				]
 			},