Block Theme (FSE Overview)

A Block Theme is a WordPress theme built using blocks and designed for Full Site Editing (FSE). It enables editing the entire site (header, footer, templates, etc.) using the Block Editor instead of traditional PHP templates.

  • Uses HTML-based templates instead of PHP
  • Powered by theme.json
  • Supports Global Styles
  • Built for Full Site Editing (FSE)
  • Uses block markup (<!-- wp:block-name -->)

Core Concepts

Theme Structure

Basic Folder Structure

my-block-theme/
│
├── style.css
├── functions.php
├── theme.json
├── screenshot.png
│
├── templates/
│   ├── index.html
│   ├── single.html
│   └── page.html
│
├── parts/
│   ├── header.html
│   └── footer.html
│
└── assets/
    ├── css/
    └── js/

Main Stylesheet (style.css)

Purpose

  • Required for theme recognition
  • Contains theme metadata
  • Can include global CSS

Example

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Ashish Verma
Description: A custom block theme
Version: 1.0
*/

body {
    margin: 0;
    font-family: sans-serif;
}

Custom Functionality (functions.php)

Purpose

  • Add theme supports
  • Register features
  • Enqueue scripts and styles

Example

<?php

function my_block_theme_setup() {
    add_theme_support( 'wp-block-styles' );
    add_theme_support( 'editor-styles' );
    add_theme_support( 'responsive-embeds' );
}

add_action( 'after_setup_theme', 'my_block_theme_setup' );

Templates (Block-Based)

Example: templates/index.html

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

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

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

Including Assets (CSS & JavaScript)

Example

function my_theme_assets() {
    wp_enqueue_style(
        'my-theme-style',
        get_stylesheet_uri(),
        [],
        wp_get_theme()->get( 'Version' )
    );

    wp_enqueue_script(
        'my-theme-script',
        get_template_directory_uri() . '/assets/js/main.js',
        [],
        null,
        true
    );
}
add_action( 'wp_enqueue_scripts', 'my_theme_assets' );

Global Settings & Styles (theme.json)

Purpose

  • Define design system (colors, typography, spacing)
  • Apply global styles across blocks

Example

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#0073aa"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "12px"
        }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#000000"
    }
  }
}

Block Patterns

What are Block Patterns?

Block Patterns are predefined layouts made up of blocks. They can be inserted from the Patterns tab in the editor and then customized.

Registering a Block Pattern

function my_register_patterns() {
    register_block_pattern(
        'my-theme/hero-section',
        [
            'title'       => __( 'Hero Section', 'my-theme' ),
            'description' => __( 'A simple hero section', 'my-theme' ),
            'content'     => '
                <!-- wp:cover {"url":"image.jpg"} -->
                <div class="wp-block-cover">
                    <span>Hero Content</span>
                </div>
                <!-- /wp:cover -->
            ',
        ]
    );
}

add_action( 'init', 'my_register_patterns' );

Register Pattern Category

register_block_pattern_category(
    'my-theme-patterns',
    [ 'label' => __( 'My Theme Patterns', 'my-theme' ) ]
);

Key Notes

  • Patterns are static definitions
  • After insertion, they become editable blocks
  • Not dynamically linked to the original pattern

Templates and Template Parts

Templates

Templates define the layout for different types of pages and are stored in the /templates directory.

Common Templates

  • index.html
  • single.html
  • page.html
  • archive.html

Template Parts

Template Parts are reusable sections like headers and footers, stored in the /parts directory.

Example: parts/header.html

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

Usage in Template

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

Registering Template Parts in theme.json

{
  "templateParts": [
    {
      "name": "header",
      "title": "Header",
      "area": "header"
    }
  ]
}

Important Notes

  • Templates are stored as a custom post type: wp_template
  • Template parts are stored as: wp_template_part

Priority Rule

Saved Template (Database)
        ↓
Overrides
        ↓
File-based Template (.html)
  • Templates edited in the Site Editor override file-based templates
  • Changes in HTML files will not reflect if a saved version exists

Minimal Block Theme Example

style.css

/*
Theme Name: Minimal Block Theme
*/

body {
    font-family: Arial, sans-serif;
}

theme.json

{
  "version": 2,
  "styles": {
    "typography": {
      "fontSize": "16px"
    }
  }
}

templates/index.html

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

<!-- wp:post-title /-->
<!-- wp:post-content /-->

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

parts/header.html

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

functions.php

<?php
add_action( 'after_setup_theme', function() {
    add_theme_support( 'wp-block-styles' );
});