Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 68 ยท Block Themes and the Site Editor

Block Themes: The Big Picture

Understand WordPress block themes - how they differ from classic themes, their folder layout, the minimum files, the Site Editor, global styles and hybrid themes.

For about fifteen years a WordPress theme meant PHP files: header.php, single.php, a loop and a pile of template tags. Block themes replace that with HTML files made of blocks, plus one JSON file for design settings. The same block editor you use to write a post now builds the whole site: header, footer, post layout, archives. A theme becomes a set of starting points that the site owner can change visually in the Site Editor.

Block themes are the direction of WordPress 6.x, and they are what new official themes use. They change what a theme developer writes every day, so this lesson gives you the map: what a block theme is made of, how it differs from a classic theme, where customizations live, and where PHP still fits. The next lessons zoom into theme.json, templates and parts and the other pieces.

WordPress itself cannot run on this site, so the theme files below are read-only. The runnable examples are plain-PHP stand-ins that show the ideas: how block markup is structured and how style layers combine.

Classic themes versus block themes

Classic theme Block theme
Templates PHP files (single.php) HTML files (templates/single.html)
Layout logic PHP, template tags, the Loop Blocks (Query Loop, Post Title, Post Content)
Reusable pieces get_template_part() Template parts in parts/
Design settings functions.php, add_theme_support(), CSS theme.json
Customizing Customizer, widgets, menus Site Editor, Styles panel
Who can change layout Developers Site owners, in the browser

Both kinds follow the same template hierarchy: WordPress looks for single-book.html the same way it would look for single-book.php. The difference is the file format and what the file contains.

The folder layout

A block theme is a folder in wp-content/themes/. This is a typical structure:

TEXT
wp-content/themes/mytheme/
  style.css            theme header comment (name, version) plus any custom CSS
  theme.json           design tokens and settings
  functions.php        optional PHP: hooks, block styles, enqueuing
  templates/
    index.html         required fallback template
    single.html
    page.html
    archive.html
    404.html
  parts/
    header.html
    footer.html
  patterns/
    hero.php           pattern with a PHP header comment
  styles/
    dark.json          style variation
  assets/
    fonts/ images/

What each part does:

  • style.css holds the theme header comment (Theme Name, Version, and so on) that WordPress reads to list the theme. In block themes it usually contains little CSS, because most styling comes from theme.json.
  • templates/ contains full-page layouts as HTML with block comments.
  • parts/ contains reusable regions such as the header and footer, included with a Template Part block.
  • patterns/ contains block patterns: pre-built sections users can insert. WordPress registers files from this folder automatically.
  • styles/ contains alternative theme.json files that appear as style variations in the Site Editor.
  • theme.json declares colors, fonts, spacing, layout widths and default styles.

The minimum

For a theme to be recognized as a block theme, it needs only two files: style.css with a header comment and templates/index.html. Everything else is optional, although a real theme almost always adds theme.json, a header and footer part, and a few more templates.

CSS
/*
Theme Name: My Theme
Theme URI: https://example.com/my-theme
Author: Your Name
Description: A small block theme for learning.
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 7.4
License: GPL-2.0-or-later
Text Domain: mytheme
*/
HTML
<!-- wp:template-part {"slug":"header"} /-->

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
  <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer"} /-->

This index.html shows a header, the post content, and a footer. There is no PHP, no get_header(), no wp_head(): core's block rendering supplies those things.

What block markup looks like

A block in a template or in saved post content is wrapped by an HTML comment that names the block and carries its settings as JSON:

HTML
<!-- wp:heading {"level":2} -->
<h2 class="wp-block-heading">Latest posts</h2>
<!-- /wp:heading -->

A block that has no inner HTML (or whose output is generated by PHP) uses a self-closing comment: <!-- wp:post-title /-->. Core blocks leave out the core/ prefix (wp:paragraph means core/paragraph), and blocks from plugins keep their namespace (wp:acme/notice). Blocks can be nested: a Group block contains other blocks between its opening and closing comments.

Because the structure is plain text, WordPress can parse it with a small tokenizer. Here is a simplified stand-in that does the same kind of job and prints the block tree of a template.

PHP A tiny block-markup parser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The parser shows why block themes are approachable: the file is a tree of named blocks with settings, and nothing in it is PHP. WordPress's real parser handles many more cases (nested JSON, escaped characters, freeform content) and also keeps the raw HTML of every block for later rendering.

flowchart TD
    A["templates/single.html"] --> B["wp:template-part header"]
    A --> C["wp:group main"]
    A --> D["wp:template-part footer"]
    C --> E["wp:post-title"]
    C --> F["wp:post-content"]
    B -. "loads" .-> G["parts/header.html"]
    D -. "loads" .-> H["parts/footer.html"]

A template is a tree of blocks; template parts pull in shared files from the parts folder.

The Site Editor and where changes are stored

In the admin, Appearance > Editor opens the Site Editor. There the owner can browse templates and parts, edit them with the block editor, change global styles (colors, typography, spacing) and switch style variations.

Edits do not rewrite your theme files. WordPress saves them in the database:

  • Template and template part changes are stored as posts of the types wp_template and wp_template_part, tagged with the theme they belong to.
  • Style changes are stored as one post of the type wp_global_styles per theme, holding JSON in the same shape as theme.json.

When WordPress needs a template, it first looks for a saved customization in the database and falls back to the file in the theme. The Site Editor's "Clear customizations" action deletes the database copy so the file shows through again. This means two things for developers: your theme files are the defaults, and a site that has been edited in the Site Editor may not show your latest file changes until its customizations are cleared.

How global styles are merged

Styles come in layers, and each layer overrides the one before it:

  1. Core defaults: WordPress's built-in presets and settings.
  2. Theme: your theme.json, and the selected style variation on top of it.
  3. User: the customizations saved from the Styles panel in the Site Editor.

WordPress merges them into one set of values and turns them into CSS custom properties and rules. The merge is recursive: a user changing only the link color leaves every other value from the theme untouched.

PHP Merging core, theme and user styles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The core values here are made up for the demo; real defaults come from WordPress. Every value in the table traces back to the layer that supplied it. The user's single change (the link color) wins over the theme's, while the theme's other values replace the core defaults.

Hybrid themes

Not every site needs to switch at once. A hybrid theme is a classic theme (PHP templates) that adopts parts of the block system. Common steps include adding a theme.json to a classic theme so the editor gets your colors, fonts and layout widths; using block-based template parts; or registering patterns. WordPress 6.x supports these combinations, though what a hybrid theme can use depends on which add_theme_support() features it opts into, so check the documentation for your WordPress version before depending on a specific one.

Where PHP still fits

A block theme does not forbid PHP. functions.php still works for registering block styles and patterns in code, enqueuing extra assets, adding theme supports and hooking filters such as render_block (see PHP in Block Themes). The big change is that layout moves out of PHP and into block markup.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two files are enough for WordPress to recognize a block theme?

    A block theme needs style.css with a theme header and templates/index.html. theme.json, parts and patterns are optional, although real themes nearly always add them.
  2. 2. You edit the header in the Site Editor and save. Where does WordPress store the change?

    Site Editor changes are saved as posts of the wp_template_part (and wp_template) types. The theme file stays as the default and is used again if the customizations are cleared.
  3. 3. Three style layers define the same link color: core, theme.json and the user's Styles panel. Which one wins?

    The layers merge in order core, theme, user, and later layers override earlier ones, so a user's customization beats the theme.
  4. 4. How does a block's markup appear in a template file?

    Blocks are delimited by comments such as <!-- wp:heading {"level":2} --> and a matching closing comment, or by a self-closing comment when there is no inner HTML.

Summary

  • Block themes build layout from HTML templates made of blocks, and design settings come from theme.json.
  • The minimum is style.css with a header and templates/index.html; common extras are parts/, patterns/, styles/ and functions.php.
  • Blocks are written as HTML comments with JSON attributes, and core blocks omit the core/ prefix.
  • Site Editor edits live in the database (wp_template, wp_template_part, wp_global_styles) and override your files until cleared.
  • Styles merge in order: core, theme (plus variation), user.
  • Hybrid themes mix classic PHP templates with block features, and PHP stays useful for hooks and registration.

Next, learn the settings file at the heart of every block theme: theme.json.