Block-based Themes (Experimental) Edit

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: 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? 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.

Top ↑

What is the structure of a block-based theme? 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, and template parts, are block templates instead of php files.

Top ↑

What is a block template? 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:

<!-- wp:site-title /-->

<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
    <img src="https://cldup.com/0BNcqkoMdq.jpg" alt="" />
</figure>
<!-- /wp:image -->

<!-- wp:group -->
<div class="wp-block-group">
    <div class="wp-block-group__inner-container">
        <!-- wp:post-title /-->
        <!-- wp:post-content /-->
    </div>
</div>
<!-- /wp:group -->

<!-- wp:group -->
<div class="wp-block-group">
    <div class="wp-block-group__inner-container">
        <!-- wp:heading -->
        <h2>Footer</h2>
        <!-- /wp:heading -->
    </div>
</div>
<!-- /wp:group -->

Top ↑

How to write and edit these templates? 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 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 within 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.

Top ↑

Edit Templates within the Full-site Editor 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.

Top ↑

Templates CPT 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.

Top ↑

Theme Blocks 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 Comments
  • Post CommentsCount
  • Post CommentsForm
  • Post Date
  • Post Excerpt
  • Post Featured Image
  • Post Tags

Top ↑

Styling 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.

Top ↑

Resources Resources