Docs: Create a Full Site Editing overview document (#31065)

* 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 * Add link to theme.json documentation * Apply suggestions from code review Thank you for fixing my embarrassing typos :-) Co-authored-by: Carolina Nymark <[email protected]> * Update docs/getting-started/full-site-editing.md * Update with TT1 Block theme available in directory * Reword jump in section, add link to tag * Add link to templates architecture doc * Remove outdated adding blocks to block theme page * Add link to block theme overview * Edits to FSE documentation - Cleaned up some of the phrasing - Added in a few more links - Made it clear to test with a test site - Added context around nav/widgets + the vision for FSE Co-authored-by: Carolina Nymark <[email protected]> Co-authored-by: annezazu <[email protected]>
WordPress · Apr 24, 2021 · c047e27 · c047e27
1 parent 54e1601
commit c047e27
Show file tree

Hide file tree

Showing 5 changed files with 74 additions and 86 deletions.
diff --git a/docs/getting-started/full-site-editing.md b/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/).
diff --git a/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md b/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md
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,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)
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,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",

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": [] },
@@ -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": [
 					{