daily notes

Block themes represent the modern approach to WordPress development, leveraging Full Site Editing (FSE) and block-based design. Unlike traditional themes that rely heavily on PHP templates, block themes are built using HTML files composed entirely of block markup.

This guide walks you through creating a block theme from the ground up, along with key concepts and best practices.

Prerequisites

Before getting started, make sure you have:

• WordPress version 5.9 or higher
• Access to the /wp-content/themes/ directory

Setting Up Your Block Theme

Create the Theme Directory

Start by creating a new folder inside the themes directory:

/wp-content/themes/my-block-theme

Add Essential Files

A minimal block theme requires the following structure:

my-block-theme/
│── style.css
│── theme.json
│── index.php
│── templates/
│   └── index.html
│── parts/

style.css

This file registers your theme with WordPress:

/*
Theme Name: My Block Theme
Author: Your Name
Version: 1.0
*/

In block themes, styling is typically not written here. Instead, it is managed through theme.json.

index.php

Even though block themes don’t use PHP templates, WordPress still requires this fallback file:

<?php
// Required fallback file

theme.json

This file defines global styles and editor configurations:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#0073aa"
        }
      ]
    }
  }
}

templates/index.html

This is your main template file, built using block markup:

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

<!-- wp:heading -->
<h1>Welcome to My Block Theme</h1>
<!-- /wp:heading -->

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

Create Template Parts

Reusable sections like headers and footers go inside the /parts directory.

Example: parts/header.html

<!-- wp:group -->
<div class="wp-block-group">
  <!-- wp:site-title /-->
</div>
<!-- /wp:group -->

Recommended Development Workflow

• Set up the theme structure manually or via the Site Editor
• Design layouts using the block editor
• Store templates in /templates
• Store reusable components in /parts
• Manage styles using theme.json
• Test changes in the Site Editor
• Export the theme if built using the UI

Core Concepts of Block Themes

• Block markup replaces traditional PHP templates
• Templates are HTML-based
• Styling is centralized using theme.json
• Full Site Editing enables visual customization without coding

Templates vs Template Parts

Templates

Templates define the structure of entire pages.

Common templates include:

• index.html (fallback)
• single.html (single post view)
• page.html (static pages)
• archive.html (category/tag listings)
• 404.html (error page)

Example: single.html

<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:post-title /-->
<!-- wp:post-content /-->
<!-- wp:template-part {"slug":"footer"} /-->

Template Parts

Template parts are reusable sections included across multiple templates.

Examples:

• Header
• Footer
• Sidebar

Example: footer.html

<!-- wp:group -->
<div class="wp-block-group">
  <!-- wp:paragraph -->
  <p>© 2026 My Site</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

Key Differences

Best Practices

• Use template parts for reusable UI elements
• Keep templates clean and minimal
• Avoid duplicating common sections like header/footer
• Follow clear and consistent naming conventions

Understanding theme.json

The theme.json file is the backbone of a block theme’s design system.

Purpose

• Define global styles (colors, typography, spacing)
• Control editor settings
• Ensure design consistency
• Reduce dependency on CSS

Basic Structure

{
  "version": 2,
  "settings": {},
  "styles": {},
  "templates": {},
  "templateParts": {}
}

Example: Typography Settings

{
  "settings": {
    "typography": {
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "12px"
        }
      ]
    }
  }
}

Example: Global Styles

{
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#000000"
    },
    "typography": {
      "fontFamily": "Arial"
    }
  }
}

Block-Level Styling

{
  "styles": {
    "blocks": {
      "core/heading": {
        "typography": {
          "fontSize": "32px"
        }
      }
    }
  }
}

Advantages of theme.json

• Centralized styling system
• Better performance
• Consistent design across pages
• Seamless integration with the block editor

Types of WordPress Themes

Classic Themes

Traditional themes built using PHP templates.

Characteristics:

• Use files like index.php, single.php
• Follow the Template Hierarchy
• Depend heavily on functions.php
• Limited FSE support

Hybrid Themes

A mix of classic and block-based approaches.

Characteristics:

• Combine PHP templates with blocks
• Partial support for theme.json
• Ideal for gradual migration

Child Themes

Themes that inherit functionality from a parent theme.

Purpose:

• Safe customization
• Preserve changes during updates
• Extend existing themes

Example Setup:

/*
Theme Name: My Child Theme
Template: parent-theme-folder
*/

<?php
function enqueue_parent_styles() {
  wp_enqueue_style('parent-style', get_template_directory_uri() . '/style.css');
}
add_action('wp_enqueue_scripts', 'enqueue_parent_styles');

Comparison Overview