From 15c33eb087cde31e47e6357b9d860044d2a09e8a Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Tue, 3 Dec 2019 18:15:33 +0100 Subject: [PATCH 01/14] Start an initial documentaton about the block based themes --- .../developers/themes/block-based-themes.md | 92 +++++++++++++++++++ docs/manifest-devhub.json | 6 ++ docs/manifest.json | 6 ++ docs/toc.json | 3 +- 4 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 docs/designers-developers/developers/themes/block-based-themes.md diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md new file mode 100644 index 00000000000000..5de76626e1cd80 --- /dev/null +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -0,0 +1,92 @@ +# Block-based themes (Experimental) + +> This is the documentation for the current implementation of the 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. + +## What is a block-based theme? + +A block-based theme is a WordPress theme that is entirely composed of blocks. 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,... + +## What is the structure of a block-based theme? + +A very simple block-based theme is structured like so: + +``` +theme +|__ style.css +|__ 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 are block templates instead of php files. + +## What is a block template? + +A block template is made 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 the templates as a theme. + +In the current iteration (at the time of writing this doc), 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. + +Once ready, switch to the "Code editor" mode and grab the HTML of the template from there and put it in the right file of your theme directory. + +## Templates CPT + +If you save the templates directly from the temporary Templates admin menu, you'd be able to override your theme's templates. Example: By using **single** as a title for your template and saving it, this saved template will take precedence over your block theme's `single.html` file. + +## 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. + +## Styling + +One of the most important aspects of themes (if not the most important) is the styles. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, this is something that is still being explored. + +## Resources + +- [Full Site Editing](https://github.com/WordPress/gutenberg/labels/%5BFeature%5D%20Full%20Site%20Editing) label. diff --git a/docs/manifest-devhub.json b/docs/manifest-devhub.json index 75573dd5ea1337..14ed6eb16cc19b 100644 --- a/docs/manifest-devhub.json +++ b/docs/manifest-devhub.json @@ -179,6 +179,12 @@ "markdown_source": "../docs/designers-developers/developers/themes/theme-support.md", "parent": "themes" }, + { + "title": "Block-based themes (Experimental)", + "slug": "block-based-themes", + "markdown_source": "../docs/designers-developers/developers/themes/block-based-themes.md", + "parent": "themes" + }, { "title": "Backward Compatibility", "slug": "backward-compatibility", diff --git a/docs/manifest.json b/docs/manifest.json index 03f85343b014a3..55a464dba9e819 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -959,6 +959,12 @@ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/themes/theme-support.md", "parent": "themes" }, + { + "title": "Block-based themes (Experimental)", + "slug": "block-based-themes", + "markdown_source": "../docs/designers-developers/developers/themes/block-based-themes.md", + "parent": "themes" + }, { "title": "Backward Compatibility", "slug": "backward-compatibility", diff --git a/docs/toc.json b/docs/toc.json index d8e264f54efeef..21cce65ff5ab8f 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -31,7 +31,8 @@ { "docs/designers-developers/developers/accessibility.md": [] }, { "docs/designers-developers/developers/feature-flags.md": [] }, { "docs/designers-developers/developers/themes/README.md": [ - { "docs/designers-developers/developers/themes/theme-support.md": [] } + { "docs/designers-developers/developers/themes/theme-support.md": [] }, + { "docs/designers-developers/developers/themes/block-based-themes.md": [] } ] }, { "docs/designers-developers/developers/backward-compatibility/README.md": [ { "docs/designers-developers/developers/backward-compatibility/deprecations.md": [] }, From 11816eb300293e080373f16c8e456a64e8457f1b Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:33:21 +0100 Subject: [PATCH 02/14] typo Co-Authored-By: Enrique Piqueras --- docs/manifest.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manifest.json b/docs/manifest.json index 55a464dba9e819..eed82cf6659fbe 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -960,7 +960,7 @@ "parent": "themes" }, { - "title": "Block-based themes (Experimental)", + "title": "Block-based Themes (Experimental)", "slug": "block-based-themes", "markdown_source": "../docs/designers-developers/developers/themes/block-based-themes.md", "parent": "themes" From 6890a606a654aadea16c0cdadfe66613683fd8cd Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:33:30 +0100 Subject: [PATCH 03/14] typo Co-Authored-By: Enrique Piqueras --- docs/manifest-devhub.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manifest-devhub.json b/docs/manifest-devhub.json index 14ed6eb16cc19b..2c4efa7d21e1ca 100644 --- a/docs/manifest-devhub.json +++ b/docs/manifest-devhub.json @@ -180,7 +180,7 @@ "parent": "themes" }, { - "title": "Block-based themes (Experimental)", + "title": "Block-based Themes (Experimental)", "slug": "block-based-themes", "markdown_source": "../docs/designers-developers/developers/themes/block-based-themes.md", "parent": "themes" @@ -1457,4 +1457,4 @@ "markdown_source": "../packages/wordcount/README.md", "parent": "packages" } -] \ No newline at end of file +] From df6d89b1e710c89800112d8e3bf2bcb538e9fb92 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:33:40 +0100 Subject: [PATCH 04/14] typo Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 5de76626e1cd80..2cff6801a72f2c 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -1,4 +1,4 @@ -# Block-based themes (Experimental) +# Block-based Themes (Experimental) > This is the documentation for the current implementation of the 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. From 5d018eb70271231a46ca4ba3c77235ca4360f970 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:33:55 +0100 Subject: [PATCH 05/14] typo Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 2cff6801a72f2c..345322eed910a4 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -1,6 +1,6 @@ # Block-based Themes (Experimental) -> This is the documentation for the current implementation of the 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. +> 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. From c3308199c9e97d5a62d5012390db040db36cf19b Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:34:17 +0100 Subject: [PATCH 06/14] clarification Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 345322eed910a4..67fdc6c765b309 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -6,7 +6,7 @@ ## What is a block-based theme? -A block-based theme is a WordPress theme that is entirely composed of blocks. 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,... +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? From 26a816055312b78b8d66723c77ace4d9fa3baed7 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:34:46 +0100 Subject: [PATCH 07/14] add template parts Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 67fdc6c765b309..1150ba7cc00650 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -28,7 +28,7 @@ theme |__ ... ``` -The difference with existing WordPress themes is that the different templates in the template hierarchy are block templates instead of php files. +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. ## What is a block template? From 3a0b51b4c82b0672e10e9e22e9318c7fe8a63496 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:35:01 +0100 Subject: [PATCH 08/14] typo Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 1150ba7cc00650..81555b1e847ad7 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -32,7 +32,7 @@ The difference with existing WordPress themes is that the different templates in ## What is a block template? -A block template is made 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. +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: From 7d00138580239c56be7967c4e590b79796a2b669 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:35:23 +0100 Subject: [PATCH 09/14] typo Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 81555b1e847ad7..9253736bc96aa3 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -67,7 +67,7 @@ Here's an example of a block template: ## 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 the templates as a theme. +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. In the current iteration (at the time of writing this doc), 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. From 692bbd77ae05f65e12b8c0e9d83b598b292e6ff3 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:35:37 +0100 Subject: [PATCH 10/14] typo Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 9253736bc96aa3..fedbdd9920a171 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -71,7 +71,7 @@ Ultimately, any WordPress user with the correct capabilities (example: `administ In the current iteration (at the time of writing this doc), 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. -Once ready, switch to the "Code editor" mode and grab the HTML of the template from there and put it in the right file of your theme directory. +When ready, switch to the "Code editor" mode and grab the HTML of the template from there and put it in the right file in your theme directory. ## Templates CPT From 2d6dfea9c988b5d5911205a647c11525b2554ac3 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:37:00 +0100 Subject: [PATCH 11/14] clarify hierarchy Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index fedbdd9920a171..1b7d3533c78ab7 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -75,7 +75,11 @@ When ready, switch to the "Code editor" mode and grab the HTML of the template f ## Templates CPT -If you save the templates directly from the temporary Templates admin menu, you'd be able to override your theme's templates. Example: By using **single** as a title for your template and saving it, this saved template will take precedence over your block theme's `single.html` file. +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 From c8ba3f3da81a6eeca313cac674afcbaad7a1aafd Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Wed, 4 Dec 2019 08:37:18 +0100 Subject: [PATCH 12/14] typo Co-Authored-By: Enrique Piqueras --- .../developers/themes/block-based-themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 1b7d3533c78ab7..3009161f9b1674 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -89,7 +89,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 styles. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, this is something that is still being explored. +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, this is an area that is still being explored. ## Resources From 6128acbde4eb36d068e8fbaa91056ee4bd28c683 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 5 Dec 2019 09:09:46 +0100 Subject: [PATCH 13/14] Add a note about the experiment flag --- .../developers/themes/block-based-themes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/designers-developers/developers/themes/block-based-themes.md index 3009161f9b1674..926c4031d2bd67 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/designers-developers/developers/themes/block-based-themes.md @@ -4,6 +4,8 @@ > 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:** In order to use these features, make sure to enable the "Full Site Editing" flag from the **Experiments** page of the Gutenberg plugin. + ## 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. @@ -89,7 +91,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, this is an area that is still being explored. +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, this is an area that is still [being explored](https://github.com/WordPress/gutenberg/issues/9534). ## Resources From 0daa1db3a9a416e9d0b7b4c34cbbb20478c814ee Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 5 Dec 2019 09:17:57 +0100 Subject: [PATCH 14/14] Fix the manifest file --- docs/manifest-devhub.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manifest-devhub.json b/docs/manifest-devhub.json index 2c4efa7d21e1ca..2fffb53c47bc3c 100644 --- a/docs/manifest-devhub.json +++ b/docs/manifest-devhub.json @@ -1457,4 +1457,4 @@ "markdown_source": "../packages/wordcount/README.md", "parent": "packages" } -] +] \ No newline at end of file