diff --git a/docs/getting-started/full-site-editing.md b/docs/getting-started/full-site-editing.md new file mode 100644 index 0000000000000..8cde8e3fabcc1 --- /dev/null +++ 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 deleted file mode 100644 index f377eac9d180c..0000000000000 --- a/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md +++ /dev/null @@ -1,53 +0,0 @@ -# Adding blocks to your theme - -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. - -There is more than one way to add blocks to the theme files: - -- Adding and editing blocks in the site editor and exporting the theme. -- Adding block HTML and comments to the HTML files manually. - -## Working with blocks and templates in the site editor - -The beta site editor is available from the WordPress admin area when full site editing is enabled. To use the site editor, a full site editing theme must be installed and active. - -The site editor is similar to the block editor, but is used for the site layout instead of the post and page content. - -Two new menus have been added to the top toolbar of the editor: - -One that shows a list of posts, pages and categories, and indicates the item that is used as the front page. - -![Site editor toolbar page menu](https://wordpress.org/gutenberg/files/2020/07/block-based-themes-page-menu.png) - -And a list of templates and template parts, that indicates the item that is being edited. Hovering over the parts will show a preview. - -![Site editor toolbar template menu](https://wordpress.org/gutenberg/files/2020/07/block-based-themes-template-menu.png) - -Template parts can be selected and edited directly in the site editor, like other blocks: - -![A selected template part is highlighted. When selected, the template part has a limited set of alignment controls in the block toolbar](https://wordpress.org/gutenberg/files/2020/07/block-based-themes-editor-template-part.png) - -Select the header template part in the menu to view and edit it individually. Add the blocks that you would like in your header, for example a site title block, a navigation block, and an image. - -Next, select the footer template part and add some content, for example widget blocks. - -Select the index template again to view the template parts together in the page context. - -To add a post loop to the index template, add a **query** block. The query block includes the query loop and the query pagination. The default loop displays the post title and post content. The query loop and query pagination are also available as individual blocks. - -## Saving templates and template parts - -When you have made your changes, click on the **update design** button in the upper right corner, -where you normally publish and update your content. - -Select the templates and template parts that you want to save: - -![The save menu displays a list of templates and template parts with checkboxes](https://wordpress.org/gutenberg/files/2020/07/block-based-themes-save.png) - -When you save changes in the site editor, the files in the active theme are not updated. Instead, the templates and template parts are saved as custom post types, that are accessed via the appearance menu. - -![The template parts view in the admin area displays a list of all saved template parts](https://wordpress.org/gutenberg/files/2020/07/block-based-themes-appearance-template-parts.png) - -## Exporting changes - -Saved templates and template parts can be exported as a partial theme from the Tools menu in the site editor. The block HTML code can then be copied to the theme that you are editing. diff --git a/docs/how-to-guides/block-based-theme/README.md b/docs/how-to-guides/block-theme/README.md similarity index 85% rename from docs/how-to-guides/block-based-theme/README.md rename to docs/how-to-guides/block-theme/README.md index d39dd3b0caaa4..92d89713ad653 100644 --- a/docs/how-to-guides/block-based-theme/README.md +++ b/docs/how-to-guides/block-theme/README.md @@ -1,10 +1,8 @@ -# 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. @@ -12,25 +10,22 @@ 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 index 208231d556a1d..e1269a28328ee 100644 --- 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 index 8d62894fb4bf0..d49e7f6942eda 100644 --- 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": [ {