From 39e2ad348d6f374eb6aa434de6bb9add2b599a39 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Sat, 24 Apr 2021 08:58:49 -0700 Subject: [PATCH 1/7] Organize block theme docs together, improve heading and links --- docs/getting-started/full-site-editing.md | 16 +- docs/how-to-guides/block-theme/README.md | 415 ++++-------------- .../block-theme/create-block-theme.md | 377 ++++++++++++++++ .../{themes => block-theme}/theme-json.md | 0 .../{themes => }/theme-support.md | 0 docs/how-to-guides/themes/README.md | 5 - .../themes/block-based-themes.md | 140 ------ docs/toc.json | 12 +- 8 files changed, 481 insertions(+), 484 deletions(-) create mode 100644 docs/how-to-guides/block-theme/create-block-theme.md rename docs/how-to-guides/{themes => block-theme}/theme-json.md (100%) rename docs/how-to-guides/{themes => }/theme-support.md (100%) delete mode 100644 docs/how-to-guides/themes/README.md delete mode 100644 docs/how-to-guides/themes/block-based-themes.md diff --git a/docs/getting-started/full-site-editing.md b/docs/getting-started/full-site-editing.md index 8cde8e3fabcc14..2902a058a271e9 100644 --- a/docs/getting-started/full-site-editing.md +++ b/docs/getting-started/full-site-editing.md @@ -1,10 +1,10 @@ # 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/). @@ -12,15 +12,15 @@ The best way to learn something is start playing with it. So jump in by installi 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/block-theme/README.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/block-theme/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. @@ -49,4 +49,4 @@ See the [architecture document on templates](docs/explanations/architecture/full 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/block-theme/theme-json.md). diff --git a/docs/how-to-guides/block-theme/README.md b/docs/how-to-guides/block-theme/README.md index 92d89713ad653a..de85a46084f482 100644 --- a/docs/how-to-guides/block-theme/README.md +++ b/docs/how-to-guides/block-theme/README.md @@ -1,377 +1,140 @@ -# Create a block theme +# Block Theme -The purpose of this tutorial is to show how to create a block theme and help theme developers transition to full site editing. +
+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. -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. +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. +
-Full site editing is an experimental feature and the workflow in this tutorial is likely to change. +## What is a block theme? -This tutorial is up to date as of Gutenberg version 9.1. +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. -## Table of Contents +## What is the structure of a block theme? -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 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. - -### Required files and file structure - -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. - -Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder: +A very simple block theme is structured like so: ``` theme |__ style.css -|__ functions.php -|__ index.php |__ experimental-theme.json +|__ functions.php |__ block-templates - |__ index.html - |__ single.html - |__ archive.html - |__ ... + |__ index.html + |__ single.html + |__ archive.html + |__ ... |__ block-template-parts - |__ header.html - |__ footer.html - |__ sidebar.html - |__ ... + |__ header.html + |__ footer.html + |__ sidebar.html + |__ ... ``` -## Creating the theme - -Create a new folder for your theme in `/wp-content/themes/`. -Inside this folder, create the `block-templates` and `block-template-parts` folders. - -Create a `style.css` file. The file header in the `style.css` file has [the same items that you would use in a traditional theme](https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/#explanations). - -``` -/* -Theme Name: My first theme -Theme URI: -Author: The WordPress team -Author URI: https://wordpress.org/ -Description: -Tags: -Version: 1.0.0 -Requires at least: 5.0 -Tested up to: 5.4 -Requires PHP: 7.0 -License: GNU General Public License v2 or later -License URI: http://www.gnu.org/licenses/gpl-2.0.html -Text Domain: myfirsttheme - -This theme, like WordPress, is licensed under the GPL. -Use it to make something cool, have fun, and share what you've learned with others. -*/ -``` - -Create a `functions.php` file. - -In this file, you will enqueue the `style.css` file and add any theme support that you want to use. For example colors, wide blocks and featured images. - -_You no longer need to add theme support for the title tag. It is already enabled with full site editing._ - -https://developer.wordpress.org/themes/basics/theme-functions/#what-is-functions-php - -https://developer.wordpress.org/block-editor/developers/themes/theme-support/ - -```php -. - */ - add_theme_support( 'automatic-feed-links' ); - - /** - * Enable support for post thumbnails and featured images. - */ - add_theme_support( 'post-thumbnails' ); - - add_theme_support( 'editor-color-palette', array( - array( - 'name' => __( 'strong magenta', 'myfirsttheme' ), - 'slug' => 'strong-magenta', - 'color' => '#a156b4', - ), - array( - 'name' => __( 'very dark gray', 'myfirsttheme' ), - 'slug' => 'very-dark-gray', - 'color' => '#444', - ), - ) ); - - add_theme_support( 'wp-block-styles' ); - - add_theme_support( 'align-wide' ); -} -endif; // myfirsttheme_setup -add_action( 'after_setup_theme', 'myfirsttheme_setup' ); - -/** - * Enqueue theme scripts and styles. - */ -function myfirsttheme_scripts() { - wp_enqueue_style( 'myfirsttheme-style', get_stylesheet_uri() ); - - if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) { - wp_enqueue_script( 'comment-reply' ); - } -} -add_action( 'wp_enqueue_scripts', 'myfirsttheme_scripts' ); -``` - -Create an `index.php` file. -This file is used as a fallback if the theme is activated when full site editing is not enabled. -You may leave the file empty for this tutorial. - -Your theme should now include the following files and folders: +The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/how-to-guides/block-theme/theme-json.md) file for some styles. -``` -theme - |__ style.css - |__ functions.php - |__ index.php - |__ block-templates - |__ (empty folder) - |__ block-template-parts - |__ (empty folder) -``` +## What is a block template? -### Creating the templates and template parts +A block template is made up of a list of blocks. Any WordPress block can be used in a template. Templates can also reuse parts of their content using "Template Parts". For example, all the block templates can have the same header included from a separate `header.html` template part. -Create two template parts called `footer.html` and `header.html` and place them inside the `block-template-parts` folder. You can leave the files empty for now. +Here's an example of a block template: -Inside the block-templates folder, create an `index.html` file. +```html + -In `index.html`, include the template parts by adding two HTML comments. + +
+ +
+ -The HTML comments starts with `wp:template-part` which is the name of the template-part block type. Inside the curly brackets are two keys and their values: The slug of the template part, and the theme text domain. + +
+ + +
+ + +
+ +

Footer

+ +
+ ``` - - -``` +## How to write and edit these templates? -If you used a different theme name, adjust the value for the theme text domain. +Ultimately, any WordPress user with the correct capabilities (example: `administrator` WordPress role) will be able to access these templates in the WordPress admin, edit them in dedicated views and potentially export them as a theme. -Eventually, you will be able to create and combine templates and template parts directly in the site editor. +As of Gutenberg 8.5, there are two ways to create and edit templates within Gutenberg. -### Experimental-theme.json - Global styles +### Edit templates within The "Appearance" section of WP-Admin -The purpose of the `experimental-theme.json` file is to make it easier to style blocks by setting defaults. +You can navigate to the temporary "Templates" admin menu under "Appearance" `wp-admin/edit.php?post_type=wp_template` and use this as a playground to edit your templates. Add blocks here and switch to the code editor mode to grab the HTML of the template when you are done. Afterwards, you can paste that markup into a file in your theme directory. -It is used to: +Please note that the "Templates" admin menu under "Appearance" will _not_ list templates that are bundled with your theme. It only lists new templates created by the specific WordPress site you're working on. -- Create CSS variables (also called CSS custom properties) that can be used to style blocks both on the front and in the editor. -- Set global styles. -- Set styles for individual block types. +### Edit Templates within the Full-site Editor -[The documentation for global styles contains a list of available block and style combinations.](https://developer.wordpress.org/block-editor/developers/themes/theme-json/) +To begin, create a blank template file within your theme. For example: `mytheme/block-templates/index.html`. Afterwards, open the Full-site editor. Your new template should appear as the active template, and should be blank. Add blocks as you normally would using Gutenberg. You can add and create template parts directly using the "Template Parts" block. -Create a file called `experimental-theme.json` and save it inside the main folder. +Repeat for any additional templates you'd like to bundle with your theme. -CSS variables are generated using **Global presets**. The variables are added to the `:root` on the front, and to the `.editor-styles-wrapper` class in the editor. +When you're done, click the "Export Theme" option in the "Tools" (ellipsis) menu of the site editor. This will provide you with a ZIP download of all the templates and template parts you've created in the site editor. These new HTML files can be placed directly into your theme. -Styles that are added to the themes `style.css` file or an editor style sheet are loaded after global styles. +Note that when you export template parts this way, the template part block markup will include a `postID` attribute that can be safely removed when distributing your theme. -Add the following global presets to the `experimental-theme.json` file: +## Templates CPT -``` -{ - "global": { - "settings": { - "color": { - "palette": [ - { - "slug": "strong-magenta", - "color": "#a156b4" - }, - { - "slug": "very-dark-gray", - "color": "#444" - }, - ] - }, - "custom": { - "line-height": [ - { - "small": "1.3" - }, - { - "medium": "2" - }, - { - "large": "2.5" - } - ] - } - } - } -} -``` +If you save the templates directly from the temporary Templates admin menu, you'll be able to override your theme's templates. -This code generates the following variables: +Example: By using **single** as the title for your template and saving it, this saved template will take precedence over your theme's `single.html` file. -``` - --wp--preset--color--strong-magenta: #a156b4; - --wp--preset--color--very-dark-gray: #444; +Note that it won't take precedence over any of your theme's templates with higher specificity in the template hierarchy. Resolution goes from most to least specific, looking first for a CPT post and then for a theme template, at each level. - --wp--custom--line-height--small: 1.3; - --wp--custom--line-height--medium: 2; - --wp--custom--line-height--large: 2.5; -``` - -**Global styles** are used to set default values for the website and for the blocks. +## Theme Blocks -This example will add the dark grey color as the website background color. -Add the code inside the globals, after the presets: +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. -``` - "styles": { - "color": { - "background": "var(--wp--preset--color--very-dark-gray)" - } - } -``` +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: -**Block styles** sets default values for all blocks of a specific type. +- Site Title +- Template Part +- Query +- Query Loop +- Query Pagination +- Post Title +- Post Content +- Post Author +- Post Comment +- Post Comment Author +- Post Comment Date +- Post Comments +- Post Comments Count +- Post Comments Form +- Post Date +- Post Excerpt +- Post Featured Image +- Post Hierarchical Terms +- Post Tags -This example uses the CSS variables to add text color and line height to the H2 heading block, -in combination with a custom font size. +## Styling -When adding styles for the headings block, include the heading level, h1 to h6. +One of the most important aspects of themes (if not the most important) is the styling. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, the [Global Styles](/docs/how-to-guides/block-theme/theme-json.md) effort will provide a scaffolding for adding many theme styles in the future. -Block styles are separate from global styles. Add the code after the globals, but before the closing brace. +## Classic Themes -``` -"core/heading/h2": { - "styles": { - "color": { - "text": "var( --wp--preset--color--strong-magenta )" - }, - "typography": { - "fontSize": "2.5rem", - "lineHeight": "var(--wp--custom--line-height--medium)" - } - } -}, -``` +Users of classic themes can also build custom block templates and use theme in their Pages and Custom Post Types that supports Page Templates. -CSS variables for font sizes are generated using the `editor-font-sizes` theme support or by adding a global preset. +Theme authors can opt-out of this feature by removing the `block-templates` theme support in their `functions.php` file. -https://developer.wordpress.org/block-editor/developers/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. - -The font sizes are unitless, which is why calc is used: https://developer.mozilla.org/en-US/docs/Web/CSS/calc - -``` -"core/paragraph": { - "styles": { - "typography": { - "fontSize": "calc(1px * var( --wp--preset--font-size--medium ))" - } - } -}, -``` - -Using the CSS variables is optional. In this example, the default background color for the group block is changed to white using a color code: - -``` -"core/group": { - "styles": { - "color": { - "background": "#ffffff" - } - } -} +```php +remove_theme_support( 'block-templates' ); ``` -Below are the presets and styles combined: - -``` -{ - "global": { - "settings": { - "color": { - "palette": [ - { - "slug": "strong-magenta", - "color": "#a156b4" - }, - { - "slug": "very-dark-gray", - "color": "#444" - }, - ] - }, - "custom": { - "line-height": [ - { - "small": "1.3" - }, - { - "medium": "2" - }, - { - "large": "2.5" - } - ] - } - } - }, - - "core/heading/h2": { - "styles": { - "color": { - "text": "var( --wp--preset--color--strong-magenta )" - }, - "typography": { - "fontSize": "2.5rem", - "lineHeight": "var(--wp--custom--line-height--medium)" - } - } - }, - - "core/paragraph": { - "styles": { - "typography": { - "fontSize": "calc(1px * var( --wp--preset--font-size--medium ))" - } - } - }, - - "core/group": { - "styles": { - "color": { - "background": "#ffffff" - } - } - } -} -``` +## 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 theme examples created by the WordPress community. diff --git a/docs/how-to-guides/block-theme/create-block-theme.md b/docs/how-to-guides/block-theme/create-block-theme.md new file mode 100644 index 00000000000000..92d89713ad653a --- /dev/null +++ b/docs/how-to-guides/block-theme/create-block-theme.md @@ -0,0 +1,377 @@ +# Create a block theme + +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. + +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-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 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. + +### Required files and file structure + +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. + +Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder: + +``` +theme +|__ style.css +|__ functions.php +|__ index.php +|__ experimental-theme.json +|__ block-templates + |__ index.html + |__ single.html + |__ archive.html + |__ ... +|__ block-template-parts + |__ header.html + |__ footer.html + |__ sidebar.html + |__ ... +``` + +## Creating the theme + +Create a new folder for your theme in `/wp-content/themes/`. +Inside this folder, create the `block-templates` and `block-template-parts` folders. + +Create a `style.css` file. The file header in the `style.css` file has [the same items that you would use in a traditional theme](https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/#explanations). + +``` +/* +Theme Name: My first theme +Theme URI: +Author: The WordPress team +Author URI: https://wordpress.org/ +Description: +Tags: +Version: 1.0.0 +Requires at least: 5.0 +Tested up to: 5.4 +Requires PHP: 7.0 +License: GNU General Public License v2 or later +License URI: http://www.gnu.org/licenses/gpl-2.0.html +Text Domain: myfirsttheme + +This theme, like WordPress, is licensed under the GPL. +Use it to make something cool, have fun, and share what you've learned with others. +*/ +``` + +Create a `functions.php` file. + +In this file, you will enqueue the `style.css` file and add any theme support that you want to use. For example colors, wide blocks and featured images. + +_You no longer need to add theme support for the title tag. It is already enabled with full site editing._ + +https://developer.wordpress.org/themes/basics/theme-functions/#what-is-functions-php + +https://developer.wordpress.org/block-editor/developers/themes/theme-support/ + +```php +. + */ + add_theme_support( 'automatic-feed-links' ); + + /** + * Enable support for post thumbnails and featured images. + */ + add_theme_support( 'post-thumbnails' ); + + add_theme_support( 'editor-color-palette', array( + array( + 'name' => __( 'strong magenta', 'myfirsttheme' ), + 'slug' => 'strong-magenta', + 'color' => '#a156b4', + ), + array( + 'name' => __( 'very dark gray', 'myfirsttheme' ), + 'slug' => 'very-dark-gray', + 'color' => '#444', + ), + ) ); + + add_theme_support( 'wp-block-styles' ); + + add_theme_support( 'align-wide' ); +} +endif; // myfirsttheme_setup +add_action( 'after_setup_theme', 'myfirsttheme_setup' ); + +/** + * Enqueue theme scripts and styles. + */ +function myfirsttheme_scripts() { + wp_enqueue_style( 'myfirsttheme-style', get_stylesheet_uri() ); + + if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) { + wp_enqueue_script( 'comment-reply' ); + } +} +add_action( 'wp_enqueue_scripts', 'myfirsttheme_scripts' ); +``` + +Create an `index.php` file. +This file is used as a fallback if the theme is activated when full site editing is not enabled. +You may leave the file empty for this tutorial. + +Your theme should now include the following files and folders: + +``` +theme + |__ style.css + |__ functions.php + |__ index.php + |__ block-templates + |__ (empty folder) + |__ block-template-parts + |__ (empty folder) +``` + +### Creating the templates and template parts + +Create two template parts called `footer.html` and `header.html` and place them inside the `block-template-parts` folder. You can leave the files empty for now. + +Inside the block-templates folder, create an `index.html` file. + +In `index.html`, include the template parts by adding two HTML comments. + +The HTML comments starts with `wp:template-part` which is the name of the template-part block type. Inside the curly brackets are two keys and their values: The slug of the template part, and the theme text domain. + +``` + + + +``` + +If you used a different theme name, adjust the value for the theme text domain. + +Eventually, you will be able to create and combine templates and template parts directly in the site editor. + +### Experimental-theme.json - Global styles + +The purpose of the `experimental-theme.json` file is to make it easier to style blocks by setting defaults. + +It is used to: + +- Create CSS variables (also called CSS custom properties) that can be used to style blocks both on the front and in the editor. +- 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/) + +Create a file called `experimental-theme.json` and save it inside the main folder. + +CSS variables are generated using **Global presets**. The variables are added to the `:root` on the front, and to the `.editor-styles-wrapper` class in the editor. + +Styles that are added to the themes `style.css` file or an editor style sheet are loaded after global styles. + +Add the following global presets to the `experimental-theme.json` file: + +``` +{ + "global": { + "settings": { + "color": { + "palette": [ + { + "slug": "strong-magenta", + "color": "#a156b4" + }, + { + "slug": "very-dark-gray", + "color": "#444" + }, + ] + }, + "custom": { + "line-height": [ + { + "small": "1.3" + }, + { + "medium": "2" + }, + { + "large": "2.5" + } + ] + } + } + } +} +``` + +This code generates the following variables: + +``` + --wp--preset--color--strong-magenta: #a156b4; + --wp--preset--color--very-dark-gray: #444; + + --wp--custom--line-height--small: 1.3; + --wp--custom--line-height--medium: 2; + --wp--custom--line-height--large: 2.5; +``` + +**Global styles** are used to set default values for the website and for the blocks. + +This example will add the dark grey color as the website background color. +Add the code inside the globals, after the presets: + +``` + "styles": { + "color": { + "background": "var(--wp--preset--color--very-dark-gray)" + } + } +``` + +**Block styles** sets default values for all blocks of a specific type. + +This example uses the CSS variables to add text color and line height to the H2 heading block, +in combination with a custom font size. + +When adding styles for the headings block, include the heading level, h1 to h6. + +Block styles are separate from global styles. Add the code after the globals, but before the closing brace. + +``` +"core/heading/h2": { + "styles": { + "color": { + "text": "var( --wp--preset--color--strong-magenta )" + }, + "typography": { + "fontSize": "2.5rem", + "lineHeight": "var(--wp--custom--line-height--medium)" + } + } +}, +``` + +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 + +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. + +The font sizes are unitless, which is why calc is used: https://developer.mozilla.org/en-US/docs/Web/CSS/calc + +``` +"core/paragraph": { + "styles": { + "typography": { + "fontSize": "calc(1px * var( --wp--preset--font-size--medium ))" + } + } +}, +``` + +Using the CSS variables is optional. In this example, the default background color for the group block is changed to white using a color code: + +``` +"core/group": { + "styles": { + "color": { + "background": "#ffffff" + } + } +} +``` + +Below are the presets and styles combined: + +``` +{ + "global": { + "settings": { + "color": { + "palette": [ + { + "slug": "strong-magenta", + "color": "#a156b4" + }, + { + "slug": "very-dark-gray", + "color": "#444" + }, + ] + }, + "custom": { + "line-height": [ + { + "small": "1.3" + }, + { + "medium": "2" + }, + { + "large": "2.5" + } + ] + } + } + }, + + "core/heading/h2": { + "styles": { + "color": { + "text": "var( --wp--preset--color--strong-magenta )" + }, + "typography": { + "fontSize": "2.5rem", + "lineHeight": "var(--wp--custom--line-height--medium)" + } + } + }, + + "core/paragraph": { + "styles": { + "typography": { + "fontSize": "calc(1px * var( --wp--preset--font-size--medium ))" + } + } + }, + + "core/group": { + "styles": { + "color": { + "background": "#ffffff" + } + } + } +} +``` + diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/block-theme/theme-json.md similarity index 100% rename from docs/how-to-guides/themes/theme-json.md rename to docs/how-to-guides/block-theme/theme-json.md diff --git a/docs/how-to-guides/themes/theme-support.md b/docs/how-to-guides/theme-support.md similarity index 100% rename from docs/how-to-guides/themes/theme-support.md rename to docs/how-to-guides/theme-support.md diff --git a/docs/how-to-guides/themes/README.md b/docs/how-to-guides/themes/README.md deleted file mode 100644 index 26609e7cf3f980..00000000000000 --- a/docs/how-to-guides/themes/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Theming for the Block Editor - -The new 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. diff --git a/docs/how-to-guides/themes/block-based-themes.md b/docs/how-to-guides/themes/block-based-themes.md deleted file mode 100644 index 6eb8608b0e02fe..00000000000000 --- a/docs/how-to-guides/themes/block-based-themes.md +++ /dev/null @@ -1,140 +0,0 @@ -# Block-based Themes (Experimental) - -> 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. - -> 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. - -## What is a block-based 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. - -## What is the structure of a block-based theme? - -A very simple block-based theme is structured like so: - -``` -theme -|__ style.css -|__ experimental-theme.json -|__ functions.php -|__ block-templates - |__ index.html - |__ single.html - |__ archive.html - |__ ... -|__ block-template-parts - |__ header.html - |__ footer.html - |__ sidebar.html - |__ ... -``` - -The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/how-to-guides/themes/theme-json.md) file for some styles. - -## What is a block template? - -A block template is made up of a list of blocks. Any WordPress block can be used in a template. Templates can also reuse parts of their content using "Template Parts". For example, all the block templates can have the same header included from a separate `header.html` template part. - -Here's an example of a block template: - -```html - - - -
- -
- - - -
- - -
- - - -
- -

Footer

- -
- -``` - -## How to write and edit these templates? - -Ultimately, any WordPress user with the correct capabilities (example: `administrator` WordPress role) will be able to access these templates in the WordPress admin, edit them in dedicated views and potentially export them as a theme. - -As of Gutenberg 8.5, there are two ways to create and edit templates within Gutenberg. - -### Edit templates within The "Appearance" section of WP-Admin - -You can navigate to the temporary "Templates" admin menu under "Appearance" `wp-admin/edit.php?post_type=wp_template` and use this as a playground to edit your templates. Add blocks here and switch to the code editor mode to grab the HTML of the template when you are done. Afterwards, you can paste that markup into a file in your theme directory. - -Please note that the "Templates" admin menu under "Appearance" will _not_ list templates that are bundled with your theme. It only lists new templates created by the specific WordPress site you're working on. - -### Edit Templates within the Full-site Editor - -To begin, create a blank template file within your theme. For example: `mytheme/block-templates/index.html`. Afterwards, open the Full-site editor. Your new template should appear as the active template, and should be blank. Add blocks as you normally would using Gutenberg. You can add and create template parts directly using the "Template Parts" block. - -Repeat for any additional templates you'd like to bundle with your theme. - -When you're done, click the "Export Theme" option in the "Tools" (ellipsis) menu of the site editor. This will provide you with a ZIP download of all the templates and template parts you've created in the site editor. These new HTML files can be placed directly into your theme. - -Note that when you export template parts this way, the template part block markup will include a `postID` attribute that can be safely removed when distributing your theme. - -## Templates CPT - -If you save the templates directly from the temporary Templates admin menu, you'll be able to override your theme's templates. - -Example: By using **single** as the title for your template and saving it, this saved template will take precedence over your theme's `single.html` file. - -Note that it won't take precedence over any of your theme's templates with higher specificity in the template hierarchy. Resolution goes from most to least specific, looking first for a CPT post and then for a theme template, at each level. - -## 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. - -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: - -- Site Title -- Template Part -- Query -- Query Loop -- Query Pagination -- Post Title -- Post Content -- Post Author -- Post Comment -- Post Comment Author -- Post Comment Date -- Post Comments -- Post Comments Count -- Post Comments Form -- Post Date -- Post Excerpt -- Post Featured Image -- Post Hierarchical Terms -- Post Tags - -## Styling - -One of the most important aspects of themes (if not the most important) is the styling. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, the [Global Styles](/docs/how-to-guides/themes/theme-json.md) effort will provide a scaffolding for adding many theme styles in the future. - -## Classic Themes - -Users of classic themes can also build custom block templates and use theme in their Pages and Custom Post Types that supports Page Templates. - -Theme authors can opt-out of this feature by removing the `block-templates` theme support in their `functions.php` file. - -```php -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. diff --git a/docs/toc.json b/docs/toc.json index d49e7f6942eda9..dd234a12e0d735 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -129,14 +129,16 @@ } ] }, - { "docs/how-to-guides/feature-flags.md": [] }, { - "docs/how-to-guides/themes/README.md": [ - { "docs/how-to-guides/themes/theme-support.md": [] }, - { "docs/how-to-guides/themes/theme-json.md": [] } + "docs/how-to-guides/block-theme/README.md": [ + { + "docs/how-to-guides/block-theme/create-block-theme.md": [] + }, + { "docs/how-to-guides/block-theme/theme-json.md": [] } ] }, - { "docs/how-to-guides/block-theme/README.md": [] }, + { "docs/how-to-guides/feature-flags.md": [] }, + { "docs/how-to-guides/theme-support.md": [] }, { "docs/how-to-guides/backward-compatibility/README.md": [ { From 8c2f488c92c8e4f792d740308d6b8a0a900dc20f Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Sat, 24 Apr 2021 08:59:16 -0700 Subject: [PATCH 2/7] Fix links to moved docs --- .../explanations/architecture/key-concepts.md | 2 +- docs/getting-started/faq.md | 2 +- docs/how-to-guides/README.md | 2 +- .../block-theme/create-block-theme.md | 18 +++++----- docs/how-to-guides/block-theme/theme-json.md | 12 ++++--- docs/how-to-guides/designers/block-design.md | 2 +- docs/how-to-guides/theme-support.md | 2 +- docs/manifest.json | 36 +++++++++---------- .../block-api/block-supports.md | 32 ++++++++--------- .../components/line-height-control/README.md | 2 +- 10 files changed, 56 insertions(+), 54 deletions(-) diff --git a/docs/explanations/architecture/key-concepts.md b/docs/explanations/architecture/key-concepts.md index 770d90462a7b22..9ad3080e5b02bf 100644 --- a/docs/explanations/architecture/key-concepts.md +++ b/docs/explanations/architecture/key-concepts.md @@ -59,4 +59,4 @@ Note: custom post types can also be initialized with a starting `post_content` t ## Global Styles (in progress) -Describes a set of configuration and default properties of blocks and their visual aspects. Global Styles is both an interface (which users access through the site editor) and a configuration system done through [a `theme.json` file](/docs/how-to-guides/themes/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what attributes are supported, what specific tools a theme offers (like a custom color palette), the available design tools present both globally and on each block, and an infrastructure that allows to enqueue only the relevant CSS based on what blocks are used on a page. +Describes a set of configuration and default properties of blocks and their visual aspects. Global Styles is both an interface (which users access through the site editor) and a configuration system done through [a `theme.json` file](/docs/how-to-guides/block-theme/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what attributes are supported, what specific tools a theme offers (like a custom color palette), the available design tools present both globally and on each block, and an infrastructure that allows to enqueue only the relevant CSS based on what blocks are used on a page. diff --git a/docs/getting-started/faq.md b/docs/getting-started/faq.md index 5a685ce6053b7a..1fb12a4fadc653 100644 --- a/docs/getting-started/faq.md +++ b/docs/getting-started/faq.md @@ -339,7 +339,7 @@ function gutenbergtheme_editor_styles() { add_action( 'enqueue_block_editor_assets', 'gutenbergtheme_editor_styles' ); ``` -_See:_ [Editor Styles](/docs/how-to-guides/themes/theme-support.md#editor-styles) +_See:_ [Editor Styles](/docs/how-to-guides/theme-support.md#editor-styles) ## Should I be concerned that Gutenberg will make my plugin obsolete? diff --git a/docs/how-to-guides/README.md b/docs/how-to-guides/README.md index 8cc028f7b2e59f..1d15a431941b77 100644 --- a/docs/how-to-guides/README.md +++ b/docs/how-to-guides/README.md @@ -32,7 +32,7 @@ See how the new editor [supports existing Meta Boxes](/docs/reference-guides/bac By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults. -There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/themes/theme-support.md). +There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/theme-support.md). ## Autocomplete diff --git a/docs/how-to-guides/block-theme/create-block-theme.md b/docs/how-to-guides/block-theme/create-block-theme.md index 92d89713ad653a..59999a69957b59 100644 --- a/docs/how-to-guides/block-theme/create-block-theme.md +++ b/docs/how-to-guides/block-theme/create-block-theme.md @@ -10,10 +10,10 @@ 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? @@ -21,13 +21,13 @@ 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 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. +The theme may optionally include an [experimental-theme.json file](/docs/how-to-guides/block-theme/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme. Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder: @@ -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/theme-support/ ```php **These features are still experimental**. “Experimental” means this is an early implementation subject to drastic and breaking changes. -> -> Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please, be welcomed to share yours in the weekly #core-editor chats as well as async via the Github issues and Pull Requests. +
+These features are still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. + +Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please share your feedback in the weekly #core-editor or #fse-outreach-experiment channels in Slack, or async in GitHub issues. +
This is documentation for the current direction and work in progress about how themes can hook into the various sub-systems that the Block Editor provides. @@ -58,7 +60,7 @@ There are some areas of styling that would benefit from having shared values tha To address this need, we've started to experiment with CSS Custom Properties, aka CSS Variables, in some places: -- **Presets**: [color palettes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes), [font sizes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes), or [gradients](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-gradient-presets) declared by the theme are converted to CSS Custom Properties and enqueued both the front-end and the editors. +- **Presets**: [color palettes](/docs/how-to-guides/theme-support.md#block-color-palettes), [font sizes](/docs/how-to-guides/theme-support.md#block-font-sizes), or [gradients](/docs/how-to-guides/theme-support.md#block-gradient-presets) declared by the theme are converted to CSS Custom Properties and enqueued both the front-end and the editors. {% codetabs %} {% Input %} diff --git a/docs/how-to-guides/designers/block-design.md b/docs/how-to-guides/designers/block-design.md index 2a71b611b94270..17dd9442ed4ac3 100644 --- a/docs/how-to-guides/designers/block-design.md +++ b/docs/how-to-guides/designers/block-design.md @@ -144,7 +144,7 @@ Check how your block looks, feels, and works on as many devices and screen sizes ### Support Gutenberg's dark background editor scheme -Check how your block looks with [dark backgrounds](/docs/how-to-guides/themes/theme-support.md#dark-backgrounds) in the editor. +Check how your block looks with [dark backgrounds](/docs/how-to-guides/theme-support.md#dark-backgrounds) in the editor. ## Examples diff --git a/docs/how-to-guides/theme-support.md b/docs/how-to-guides/theme-support.md index 404647d6004ae5..a89e2ba37057d8 100644 --- a/docs/how-to-guides/theme-support.md +++ b/docs/how-to-guides/theme-support.md @@ -397,7 +397,7 @@ Using the Gutenberg plugin (version 8.3 or later), link color control is availab add_theme_support('experimental-link-color'); ``` -If a theme opts in, it should [define default link colors](https://developer.wordpress.org/block-editor/developers/themes/theme-json/#color-properties) in `experimental-theme.json` (or in its theme styles if no `experimental-theme.json` is present). For example: +If a theme opts in, it should [define default link colors](/docs/how-to-guides/block-theme/theme-json.md#color-properties) in `experimental-theme.json` (or in its theme styles if no `experimental-theme.json` is present). For example: ```css { diff --git a/docs/manifest.json b/docs/manifest.json index e1269a28328eee..1fb4deee6bba34 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -294,33 +294,33 @@ "parent": "block-tutorial" }, { - "title": "Feature Flags", - "slug": "feature-flags", - "markdown_source": "../docs/how-to-guides/feature-flags.md", + "title": "Block Theme", + "slug": "block-theme", + "markdown_source": "../docs/how-to-guides/block-theme/README.md", "parent": "how-to-guides" }, { - "title": "Theming for the Block Editor", - "slug": "themes", - "markdown_source": "../docs/how-to-guides/themes/README.md", - "parent": "how-to-guides" + "title": "Create a block theme", + "slug": "create-block-theme", + "markdown_source": "../docs/how-to-guides/block-theme/create-block-theme.md", + "parent": "block-theme" }, { - "title": "Theme Support", - "slug": "theme-support", - "markdown_source": "../docs/how-to-guides/themes/theme-support.md", - "parent": "themes" + "title": "Global Settings (theme.json)", + "slug": "theme-json", + "markdown_source": "../docs/how-to-guides/block-theme/theme-json.md", + "parent": "block-theme" }, { - "title": "Themes & Block Editor: experimental theme.json", - "slug": "theme-json", - "markdown_source": "../docs/how-to-guides/themes/theme-json.md", - "parent": "themes" + "title": "Feature Flags", + "slug": "feature-flags", + "markdown_source": "../docs/how-to-guides/feature-flags.md", + "parent": "how-to-guides" }, { - "title": "Create a block theme", - "slug": "block-theme", - "markdown_source": "../docs/how-to-guides/block-theme/README.md", + "title": "Theme Support", + "slug": "theme-support", + "markdown_source": "../docs/how-to-guides/theme-support.md", "parent": "how-to-guides" }, { diff --git a/docs/reference-guides/block-api/block-supports.md b/docs/reference-guides/block-api/block-supports.md index 97ee464b7fa1d3..8315af61b369c2 100644 --- a/docs/reference-guides/block-api/block-supports.md +++ b/docs/reference-guides/block-api/block-supports.md @@ -57,7 +57,7 @@ attributes: { - Type: `boolean` - Default value: `true` -This property allows to enable [wide alignment](/docs/how-to-guides/themes/theme-support.md#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`. +This property allows to enable [wide alignment](/docs/how-to-guides/theme-support.md#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`. ```js supports: { @@ -143,7 +143,7 @@ When the block declares support for `color.background`, the attributes definitio When a user chooses from the list of preset background colors, the preset slug is stored in the `backgroundColor` attribute. - Background color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes). + Background color presets are sourced from the `editor-color-palette` [theme support](/docs/how-to-guides/theme-support.md#block-color-palettes). The block can apply a default preset background color by specifying its own attribute with a default e.g.: @@ -157,7 +157,7 @@ When the block declares support for `color.background`, the attributes definitio ``` - `style`: attribute of `object` type with no default assigned. - + When a custom background color is selected (i.e. using the custom color picker), the custom color value is stored in the `style.color.background` attribute. The block can apply a default custom background color by specifying its own attribute with a default e.g.: @@ -194,7 +194,7 @@ supports: { } ``` -Duotone presets are sourced from `color.duotone` in [theme.json](https://developer.wordpress.org/block-editor/developers/themes/theme-json/). +Duotone presets are sourced from `color.duotone` in [theme.json](/docs/how-to-guides/block-theme/theme-json.md). When the block declares support for `color.duotone`, the attributes definition is extended to include the attribute `style`: @@ -234,7 +234,7 @@ supports: { } ``` -Gradient presets are sourced from `editor-gradient-presets` [theme support](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-gradient-presets). +Gradient presets are sourced from `editor-gradient-presets` [theme support](/docs/how-to-guides/theme-support.md#block-gradient-presets). When the block declares support for `color.gradient`, the attributes definition is extended to include two new attributes: `gradient` and `style`: @@ -244,7 +244,7 @@ When the block declares support for `color.gradient`, the attributes definition When a user chooses from the list of preset gradients, the preset slug is stored in the `gradient` attribute. The block can apply a default preset gradient by specifying its own attribute with a default e.g.: - + ```js attributes: { gradient: { @@ -255,9 +255,9 @@ When the block declares support for `color.gradient`, the attributes definition ``` - `style`: attribute of `object` type with no default assigned. - + When a custom gradient is selected (i.e. using the custom gradient picker), the custom gradient value is stored in the `style.color.gradient` attribute. - + The block can apply a default custom gradient by specifying its own attribute with a default e.g.: ```js @@ -296,15 +296,15 @@ supports: { } ``` -Text color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes). - +Text color presets are sourced from the `editor-color-palette` [theme support](/docs/how-to-guides/theme-support.md#block-color-palettes). + When the block declares support for `color.text`, the attributes definition is extended to include two new attributes: `textColor` and `style`: - `textColor`: attribute of `string` type with no default assigned. When a user chooses from the list of preset text colors, the preset slug is stored in the `textColor` attribute. - + The block can apply a default preset text color by specifying its own attribute with a default e.g.: ```js @@ -317,9 +317,9 @@ When the block declares support for `color.text`, the attributes definition is e ``` - `style`: attribute of `object` type with no default assigned. - + When a custom text color is selected (i.e. using the custom color picker), the custom color value is stored in the `style.color.text` attribute. - + The block can apply a default custom text color by specifying its own attribute with a default e.g.: ```js @@ -370,7 +370,7 @@ supports: { This value signals that a block supports the font-size CSS style property. When it does, the block editor will show an UI control for the user to set its value. -The values shown in this control are the ones declared by the theme via the `editor-font-sizes` [theme support](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes), or the default ones if none is provided. +The values shown in this control are the ones declared by the theme via the `editor-font-sizes` [theme support](/docs/how-to-guides/theme-support.md#block-font-sizes), or the default ones if none is provided. ```js supports: { @@ -440,7 +440,7 @@ supports: { - Type: `boolean` - Default value: `false` -This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if [the theme declares support](/docs/how-to-guides/themes/theme-support.md#supporting-custom-line-heights). +This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if [the theme declares support](/docs/how-to-guides/theme-support.md#supporting-custom-line-heights). ```js supports: { @@ -499,7 +499,7 @@ supports: { - Subproperties: - `padding`: type `boolean`, default value `false` -This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if [the theme declares support](/docs/how-to-guides/themes/theme-support.md##cover-block-padding). +This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if [the theme declares support](/docs/how-to-guides/theme-support.md#cover-block-padding). ```js supports: { diff --git a/packages/block-editor/src/components/line-height-control/README.md b/packages/block-editor/src/components/line-height-control/README.md index ca61544e9c541d..d00b8301c71489 100644 --- a/packages/block-editor/src/components/line-height-control/README.md +++ b/packages/block-editor/src/components/line-height-control/README.md @@ -4,7 +4,7 @@ The `LineHeightControl` component adds a lineHeight attribute to the core Paragr ![Line height control in a paragraph block](https://make.wordpress.org/core/files/2020/09/line-height-for-paragraph-block.png) -_Note:_ It is worth noting that the line height setting option is an opt-in feature. [Themes need to declare support for it](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#supporting-custom-line-heights) before it'll be available. +_Note:_ It is worth noting that the line height setting option is an opt-in feature. [Themes need to declare support for it](/docs/how-to-guides/theme-support.md#supporting-custom-line-heights) before it'll be available. ## Table of contents From ec753407881b43f240a7fd0a5581e587dbcd7625 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Sat, 24 Apr 2021 09:29:02 -0700 Subject: [PATCH 3/7] Typo and link fix --- docs/getting-started/full-site-editing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/full-site-editing.md b/docs/getting-started/full-site-editing.md index 2902a058a271e9..638cb389ccfaf4 100644 --- a/docs/getting-started/full-site-editing.md +++ b/docs/getting-started/full-site-editing.md @@ -24,7 +24,7 @@ If you are using the Gutenberg plugin you can run, test, and develop 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,7 +43,7 @@ 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 From 207e26026bcb248d50b10ac9f400b64b4d113d89 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Sun, 25 Apr 2021 07:58:44 -0700 Subject: [PATCH 4/7] Reorganize around themes/ dir instead of block-theme/ --- docs/how-to-guides/themes/README.md | 10 ++++++ .../block-theme-overview.md} | 0 .../create-block-theme.md | 0 .../{block-theme => themes}/theme-json.md | 0 .../{ => themes}/theme-support.md | 0 docs/manifest.json | 32 +++++++++++-------- docs/toc.json | 11 +++---- 7 files changed, 34 insertions(+), 19 deletions(-) create mode 100644 docs/how-to-guides/themes/README.md rename docs/how-to-guides/{block-theme/README.md => themes/block-theme-overview.md} (100%) rename docs/how-to-guides/{block-theme => themes}/create-block-theme.md (100%) rename docs/how-to-guides/{block-theme => themes}/theme-json.md (100%) rename docs/how-to-guides/{ => themes}/theme-support.md (100%) diff --git a/docs/how-to-guides/themes/README.md b/docs/how-to-guides/themes/README.md new file mode 100644 index 00000000000000..b92293a5f00a17 --- /dev/null +++ b/docs/how-to-guides/themes/README.md @@ -0,0 +1,10 @@ +# Themes + +The block editor provides a number of options for theme designers and developers, including theme-defined color settings, font size control, and much more. + +**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) diff --git a/docs/how-to-guides/block-theme/README.md b/docs/how-to-guides/themes/block-theme-overview.md similarity index 100% rename from docs/how-to-guides/block-theme/README.md rename to docs/how-to-guides/themes/block-theme-overview.md diff --git a/docs/how-to-guides/block-theme/create-block-theme.md b/docs/how-to-guides/themes/create-block-theme.md similarity index 100% rename from docs/how-to-guides/block-theme/create-block-theme.md rename to docs/how-to-guides/themes/create-block-theme.md diff --git a/docs/how-to-guides/block-theme/theme-json.md b/docs/how-to-guides/themes/theme-json.md similarity index 100% rename from docs/how-to-guides/block-theme/theme-json.md rename to docs/how-to-guides/themes/theme-json.md diff --git a/docs/how-to-guides/theme-support.md b/docs/how-to-guides/themes/theme-support.md similarity index 100% rename from docs/how-to-guides/theme-support.md rename to docs/how-to-guides/themes/theme-support.md diff --git a/docs/manifest.json b/docs/manifest.json index 1fb4deee6bba34..de2f1851118fd7 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -294,22 +294,34 @@ "parent": "block-tutorial" }, { - "title": "Block Theme", - "slug": "block-theme", - "markdown_source": "../docs/how-to-guides/block-theme/README.md", + "title": "Themes", + "slug": "themes", + "markdown_source": "../docs/how-to-guides/themes/README.md", "parent": "how-to-guides" }, + { + "title": "Block Theme", + "slug": "block-theme-overview", + "markdown_source": "../docs/how-to-guides/themes/block-theme-overview.md", + "parent": "themes" + }, { "title": "Create a block theme", "slug": "create-block-theme", - "markdown_source": "../docs/how-to-guides/block-theme/create-block-theme.md", - "parent": "block-theme" + "markdown_source": "../docs/how-to-guides/themes/create-block-theme.md", + "parent": "themes" }, { "title": "Global Settings (theme.json)", "slug": "theme-json", - "markdown_source": "../docs/how-to-guides/block-theme/theme-json.md", - "parent": "block-theme" + "markdown_source": "../docs/how-to-guides/themes/theme-json.md", + "parent": "themes" + }, + { + "title": "Theme Support", + "slug": "theme-support", + "markdown_source": "../docs/how-to-guides/themes/theme-support.md", + "parent": "themes" }, { "title": "Feature Flags", @@ -317,12 +329,6 @@ "markdown_source": "../docs/how-to-guides/feature-flags.md", "parent": "how-to-guides" }, - { - "title": "Theme Support", - "slug": "theme-support", - "markdown_source": "../docs/how-to-guides/theme-support.md", - "parent": "how-to-guides" - }, { "title": "Backward Compatibility", "slug": "backward-compatibility", diff --git a/docs/toc.json b/docs/toc.json index dd234a12e0d735..d9f66b3d635550 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -130,15 +130,14 @@ ] }, { - "docs/how-to-guides/block-theme/README.md": [ - { - "docs/how-to-guides/block-theme/create-block-theme.md": [] - }, - { "docs/how-to-guides/block-theme/theme-json.md": [] } + "docs/how-to-guides/themes/README.md": [ + { "docs/how-to-guides/themes/block-theme-overview.md": [] }, + { "docs/how-to-guides/themes/create-block-theme.md": [] }, + { "docs/how-to-guides/themes/theme-json.md": [] }, + { "docs/how-to-guides/themes/theme-support.md": [] } ] }, { "docs/how-to-guides/feature-flags.md": [] }, - { "docs/how-to-guides/theme-support.md": [] }, { "docs/how-to-guides/backward-compatibility/README.md": [ { From 237a4934bc38d7d559c5dd0d6c407c3a9cc5fbd5 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Sun, 25 Apr 2021 08:03:39 -0700 Subject: [PATCH 5/7] Update links to the themes/ dir --- docs/explanations/architecture/key-concepts.md | 2 +- docs/getting-started/faq.md | 4 ++-- docs/getting-started/full-site-editing.md | 6 +++--- docs/how-to-guides/README.md | 2 +- docs/how-to-guides/designers/block-design.md | 2 +- .../how-to-guides/themes/block-theme-overview.md | 4 ++-- docs/how-to-guides/themes/create-block-theme.md | 8 ++++---- docs/how-to-guides/themes/theme-json.md | 2 +- docs/how-to-guides/themes/theme-support.md | 2 +- .../reference-guides/block-api/block-supports.md | 16 ++++++++-------- .../src/components/line-height-control/README.md | 2 +- 11 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/explanations/architecture/key-concepts.md b/docs/explanations/architecture/key-concepts.md index 9ad3080e5b02bf..770d90462a7b22 100644 --- a/docs/explanations/architecture/key-concepts.md +++ b/docs/explanations/architecture/key-concepts.md @@ -59,4 +59,4 @@ Note: custom post types can also be initialized with a starting `post_content` t ## Global Styles (in progress) -Describes a set of configuration and default properties of blocks and their visual aspects. Global Styles is both an interface (which users access through the site editor) and a configuration system done through [a `theme.json` file](/docs/how-to-guides/block-theme/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what attributes are supported, what specific tools a theme offers (like a custom color palette), the available design tools present both globally and on each block, and an infrastructure that allows to enqueue only the relevant CSS based on what blocks are used on a page. +Describes a set of configuration and default properties of blocks and their visual aspects. Global Styles is both an interface (which users access through the site editor) and a configuration system done through [a `theme.json` file](/docs/how-to-guides/themes/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what attributes are supported, what specific tools a theme offers (like a custom color palette), the available design tools present both globally and on each block, and an infrastructure that allows to enqueue only the relevant CSS based on what blocks are used on a page. diff --git a/docs/getting-started/faq.md b/docs/getting-started/faq.md index 1fb12a4fadc653..87ac239e031906 100644 --- a/docs/getting-started/faq.md +++ 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? @@ -339,7 +339,7 @@ function gutenbergtheme_editor_styles() { add_action( 'enqueue_block_editor_assets', 'gutenbergtheme_editor_styles' ); ``` -_See:_ [Editor Styles](/docs/how-to-guides/theme-support.md#editor-styles) +_See:_ [Editor Styles](/docs/how-to-guides/themes/theme-support.md#editor-styles) ## Should I be concerned that Gutenberg will make my plugin obsolete? diff --git a/docs/getting-started/full-site-editing.md b/docs/getting-started/full-site-editing.md index 638cb389ccfaf4..62bfb4ac96bbca 100644 --- a/docs/getting-started/full-site-editing.md +++ b/docs/getting-started/full-site-editing.md @@ -18,9 +18,9 @@ An ongoing [FSE Outreach program](https://make.wordpress.org/test/handbook/full- ## 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/block-theme/README.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/create-block-theme.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. @@ -49,4 +49,4 @@ See the [architecture document on templates](/docs/explanations/architecture/ful 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](/docs/how-to-guides/block-theme/theme-json.md). +See [documentation for theme.json](/docs/how-to-guides/themes/theme-json.md). diff --git a/docs/how-to-guides/README.md b/docs/how-to-guides/README.md index 1d15a431941b77..8cc028f7b2e59f 100644 --- a/docs/how-to-guides/README.md +++ b/docs/how-to-guides/README.md @@ -32,7 +32,7 @@ See how the new editor [supports existing Meta Boxes](/docs/reference-guides/bac By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults. -There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/theme-support.md). +There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/themes/theme-support.md). ## Autocomplete diff --git a/docs/how-to-guides/designers/block-design.md b/docs/how-to-guides/designers/block-design.md index 17dd9442ed4ac3..2a71b611b94270 100644 --- a/docs/how-to-guides/designers/block-design.md +++ b/docs/how-to-guides/designers/block-design.md @@ -144,7 +144,7 @@ Check how your block looks, feels, and works on as many devices and screen sizes ### Support Gutenberg's dark background editor scheme -Check how your block looks with [dark backgrounds](/docs/how-to-guides/theme-support.md#dark-backgrounds) in the editor. +Check how your block looks with [dark backgrounds](/docs/how-to-guides/themes/theme-support.md#dark-backgrounds) in the editor. ## Examples diff --git a/docs/how-to-guides/themes/block-theme-overview.md b/docs/how-to-guides/themes/block-theme-overview.md index de85a46084f482..9098cb76930eaa 100644 --- a/docs/how-to-guides/themes/block-theme-overview.md +++ b/docs/how-to-guides/themes/block-theme-overview.md @@ -31,7 +31,7 @@ theme |__ ... ``` -The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/how-to-guides/block-theme/theme-json.md) file for some styles. +The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/how-to-guides/themes/theme-json.md) file for some styles. ## What is a block template? @@ -122,7 +122,7 @@ As we're still early in the process, the number of blocks specifically dedicated ## Styling -One of the most important aspects of themes (if not the most important) is the styling. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, the [Global Styles](/docs/how-to-guides/block-theme/theme-json.md) effort will provide a scaffolding for adding many theme styles in the future. +One of the most important aspects of themes (if not the most important) is the styling. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, the [Global Styles](/docs/how-to-guides/themes/theme-json.md) effort will provide a scaffolding for adding many theme styles in the future. ## Classic Themes diff --git a/docs/how-to-guides/themes/create-block-theme.md b/docs/how-to-guides/themes/create-block-theme.md index 59999a69957b59..86797bc2424e0a 100644 --- a/docs/how-to-guides/themes/create-block-theme.md +++ b/docs/how-to-guides/themes/create-block-theme.md @@ -27,7 +27,7 @@ Each template or template part contains the [block grammar](/docs/explanations/a 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/block-theme/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme. +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. Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder: @@ -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/how-to-guides/theme-support/ +https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/ ```php Date: Sun, 25 Apr 2021 08:20:55 -0700 Subject: [PATCH 6/7] Update couple more uses of block-based theme --- .../architecture/full-site-editing-templates.md | 12 +++++++----- docs/getting-started/glossary.md | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/explanations/architecture/full-site-editing-templates.md b/docs/explanations/architecture/full-site-editing-templates.md index 10f1ac3d537ad8..792a2edd88358d 100644 --- a/docs/explanations/architecture/full-site-editing-templates.md +++ b/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. +
+ 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. +
-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. diff --git a/docs/getting-started/glossary.md b/docs/getting-started/glossary.md index 02327c0eb36e01..6518868b098564 100644 --- a/docs/getting-started/glossary.md +++ b/docs/getting-started/glossary.md @@ -11,7 +11,7 @@
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.
Block Based Theme
-
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.
+
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.
Block categories
These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Library.
From 36d06ba1f5501011e0ee43b6151b3c280d174532 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Sun, 25 Apr 2021 10:48:20 -0700 Subject: [PATCH 7/7] Formating spaces --- docs/explanations/architecture/full-site-editing-templates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanations/architecture/full-site-editing-templates.md b/docs/explanations/architecture/full-site-editing-templates.md index 792a2edd88358d..dac115ef92ce8a 100644 --- a/docs/explanations/architecture/full-site-editing-templates.md +++ b/docs/explanations/architecture/full-site-editing-templates.md @@ -3,8 +3,8 @@ ## Template and template part flows
- 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. -
+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. + 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).