WordPress Full Site Editing — Block Themes and theme.json Complete Guide

In this tutorial, you'll learn WordPress Full Site Editing (FSE) — how block themes work, configuring theme.json for global styles, editing headers and footers with blocks, and building complete sites without writing PHP code.

What You'll Learn

• What Full Site Editing is (introduced in WP 5.9, matured in WP 6.0+)
• Block themes vs classic themes and when to use each
• Theme.json — the central config file for styles, settings, colors, typography
• Template parts (header, footer) edited visually with blocks
• The Site Editor interface (Appearance > Editor)
• Editing all templates (index, singular, page, archive, 404)
• Global styles (colors, typography, layout via the UI)
• Block theme installation (Twenty Twenty-Three, Twenty Twenty-Four)
• Creating a block theme from scratch (minimum: style.css, theme.json, templates/index.html)
• FSE limitations and when not to use it

Why It Matters

Full Site Editing represents the biggest shift in WordPress theming since the Customizer. Instead of editing PHP template files, headers, footers, sidebars, and even the 404 page are all editable with blocks in the visual editor. For non-developers, this means building custom layouts without touching code. For developers, it means faster prototyping, consistent design tokens via theme.json, and less template file maintenance. Understanding FSE is essential for modern WordPress development.

Real-World Use

A small business owner wants a custom homepage with a hero section, three feature columns, a testimonial slider, and a footer with social links. With a classic theme, this requires PHP templates, CSS, and possibly a page Builder. With FSE, you install a block theme, open the Site Editor, and build the entire layout with blocks — no PHP, no external builder. The theme.json file ensures consistent colors and typography across all blocks.

Learning Path

flowchart LR
  A[Theme Anatomy] --> B[Installing Themes]
  B --> C[Full Site Editing]
  C --> D[Customizer]
  D --> E[Widgets]
  E --> F[Menus]
  F --> G[Child Themes]
  G --> H[Template Hierarchy]
  H --> I[CSS Customization]
  style C fill:#4a90d9,color:#fff

What Is Full Site Editing?

Full Site Editing (FSE) is a WordPress feature introduced in version 5.9 that lets you edit every part of your site using blocks — not just post content, but headers, footers, sidebars, archives, search results, and the 404 page.

FSE is built on three pillars:

1. Block Themes — Themes that use HTML block markup instead of PHP template files
2. Site Editor — A dedicated interface (Appearance > Editor) for editing templates
3. Global Styles — Centralized style settings via theme.json or the UI

Block Themes vs Classic Themes

A block theme can include PHP files (functions.php) for enqueuing scripts or adding features, but the core templates are HTML with block markup.

Theme.json — The Central Configuration File

The theme.json file replaces dozens of add_theme_support() calls, customizer settings, and hardcoded CSS variables. It lives in the theme root:

my-block-theme/
  style.css
  theme.json
  templates/
    index.html
  parts/
    header.html
    footer.html

Basic theme.json Structure

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#1a73e8"
        },
        {
          "name": "Secondary",
          "slug": "secondary",
          "color": "#34a853"
        },
        {
          "name": "Background",
          "slug": "background",
          "color": "#ffffff"
        },
        {
          "name": "Text",
          "slug": "text",
          "color": "#202124"
        }
      ],
      "gradients": [],
      "duotone": []
    },
    "typography": {
      "fontFamilies": [
        {
          "name": "System Font",
          "slug": "system",
          "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
        },
        {
          "name": "Serif",
          "slug": "serif",
          "fontFamily": "Georgia, 'Times New Roman', serif"
        }
      ],
      "fontSizes": [
        { "name": "Small", "slug": "small", "size": "0.875rem" },
        { "name": "Medium", "slug": "medium", "size": "1rem" },
        { "name": "Large", "slug": "large", "size": "1.25rem" },
        { "name": "X-Large", "slug": "x-large", "size": "2rem" }
      ]
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "blocks": {
      "core/paragraph": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--medium)"
        }
      },
      "core/heading": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--x-large)"
        }
      }
    }
  }
}

What theme.json Controls

• Settings: What is available to the user (colors, fonts, spacing, layout)
• Styles: Default styles applied to blocks and elements
• Custom templates: Register custom page templates
• Template parts: Define available template parts areas

The version field should be 2 for current FSE themes.

Template Parts

Template parts are reusable block areas. The most common are header and footer:

parts/header.html

<!-- wp:group {"tagName":"header","style":{"spacing":{"padding":{"top":"1rem","bottom":"1rem"}}}} -->
<header class="wp-block-group">
  <!-- wp:site-title /-->
  <!-- wp:navigation {"ref":3} /-->
</header>
<!-- /wp:group -->

parts/footer.html

<!-- wp:group {"tagName":"footer","style":{"spacing":{"padding":{"top":"2rem","bottom":"2rem"}}}} -->
<footer class="wp-block-group">
  <!-- wp:paragraph {"align":"center"} -->
  <p class="has-text-align-center">Copyright 2026 My Site</p>
  <!-- /wp:paragraph -->
</footer>
<!-- /wp:group -->

You can create custom template parts (e.g., parts/sidebar.html) and insert them into templates using the block inserter.

Editing Templates with the Site Editor

The Site Editor is accessed via Appearance > Editor (only visible when a block theme is active).

Available Templates

• Index — The main fallback template
• Singular — Used for single posts and pages
• Page — Specific to pages (overrides singular)
• Single Post — Specific to posts (overrides singular)
• Archive — Category, tag, author archives
• Search — Search results page
• 404 — Page not found
• Blank — Full-width canvas for custom layouts

Editing a Template

1. Open Appearance > Editor.
2. Click on the WordPress logo in the top left to see the template list.
3. Click Templates to see all available templates.
4. Select the template you want to edit (e.g., Single Post).
5. The block editor opens with the current template layout.
6. Add, remove, or rearrange blocks as needed.
7. Click Save to apply changes.

Global Styles

Global Styles let you change colors, typography, and layout settings from the UI. Any changes you make in Global Styles override theme.json settings.

Accessing Global Styles

1. Open the Site Editor (Appearance > Editor).
2. Click the Styles icon (half-black/half-white circle) in the top right.
3. Browse typography, colors, layout, and spacing options.

What You Can Change

• Typography: Font family, size, line height, letter spacing
• Colors: Text, background, links, button colors
• Layout: Content width, wide width
• Blocks: Override styles per block type (headings, paragraphs, buttons)

Changes are stored in the database and persist across theme updates — they do not modify theme.json files.

Block Theme Installation

Installing a block theme is the same as any theme:

1. Go to Appearance > Themes > Add New.
2. Search for "Twenty Twenty-Four" or any block theme.
3. Click Install then Activate.
4. After activation, Appearance > Editor becomes available.

Popular starter block themes include:

• Twenty Twenty-Four — The default WordPress theme, full FSE support
• Twenty Twenty-Three — Style variations, minimalist
• Kadence — Block theme with advanced features
• Blockbase — Automattic's starter block theme
• Create Block Theme — A plugin that lets you create and export block themes

Creating a Block Theme from Scratch

You need a minimum of three files:

1. style.css

/*
Theme Name: My Block Theme
Description: A minimal block theme for learning FSE.
Author: Your Name
Version: 1.0.0
Text Domain: my-block-theme
*/

2. theme.json

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#1a73e8"
        },
        {
          "name": "White",
          "slug": "white",
          "color": "#ffffff"
        },
        {
          "name": "Dark",
          "slug": "dark",
          "color": "#1a1a2e"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "name": "Inter",
          "slug": "inter",
          "fontFamily": "'Inter', sans-serif"
        }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1140px"
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--white)",
      "text": "var(--wp--preset--color--dark)"
    }
  }
}

3. templates/index.html

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:query {"queryId":0,"query":{"perPage":10,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","sticky":"","inherit":true}} -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-date /-->
      <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

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

This theme displays a blog with header, post list, and footer — no PHP templates needed.

FSE Limitations

While powerful, FSE has limitations:

1. Host compatibility — Some managed WordPress hosts restrict file writing, so the Site Editor cannot save template changes. You must edit template files directly and upload via FTP.

2. Learning curve — Users familiar with the classic Customizer find the Site Editor disorienting. The dual interface (Editor + Styles) takes time to learn.

3. Plugin conflicts — Not all plugins support FSE. Plugins that inject content via hooks may not appear in block templates.

4. Performance — Block themes can be heavier than classic themes because of block rendering overhead. Optimize with Caching and minimize block nesting.

5. Template file editing — If you modify block templates by editing HTML files directly, the Site Editor shows a "modified" indicator. You must choose between keeping the code version or the UI version.

Common Mistakes

1. Using mismatched theme.json version — Use "version": 2 for modern FSE. Version 1 is deprecated and lacks many features.

2. Editing HTML templates directly then using the Site Editor — If you edit templates/header.html by hand and then save from the Site Editor, your manual edits are overwritten. Use one method consistently.

3. Forgetting to include template parts — A block theme without parts/header.html or parts/footer.html referenced in templates will not display a header or footer. Always include template part references.

4. Not registering font families properly — Font families in theme.json must use the CSS fontFamily string, not just a font name. System fonts require the full stack.

5. Overriding theme.json with UI changes and forgetting to export — UI style changes are stored in the database. If you switch themes, those changes are lost. Use the Create Block Theme plugin to export UI changes back into theme.json.

Practice Questions

1. What is the difference between a classic theme and a block theme (FSE) in terms of template files and the editing experience?

2. What role does the theme.json file play in a block theme? Give three examples of settings it controls.

3. How do you create a custom header in an FSE theme without writing PHP? What file would you create and what is its basic structure?

Challenge: Create a minimal block theme from scratch with exactly four files: style.css, theme.json, templates/index.html, and parts/header.html. Activate the theme and use the Site Editor to add a footer template part. Verify the Site Editor loads without errors and changes persist after saving.

FAQ

Mini Project

Build a complete block theme called "FSE Basics" with the following:

1. style.css — Theme header with name, author, version, text domain
2. theme.json — Custom color palette (primary blue, secondary green, dark text, light background), system font, content width 800px
3. parts/header.html — Site title and navigation block
4. parts/footer.html — Copyright paragraph with centered alignment
5. templates/index.html — Header template part, query loop showing post titles and excerpts, footer template part
6. templates/404.html — Header, "Page Not Found" heading, link back to home, footer

Activate the theme. Use the Site Editor to change the primary color to a different blue. Add a custom 404 illustration using the Image block. Save and verify on the front end.

What's Next

Now that you understand Full Site Editing, learn how to use the theme customizer for classic themes and additional tweaks. Then explore block widgets and widget areas to manage sidebar content. Finally, master the template hierarchy to understand how WordPress selects templates.