WordPress Block Theme Development: A Beginner’s Guide

The quickest reliable way to build a modern WordPress block theme is to start with three files—templates/index.html, style.css, and theme.json—then add templates, template parts, and patterns as your site needs them. Block markup defines the page structure, theme.json centralizes design settings, and the Site Editor lets you refine the same files visually. This guide takes you from an empty theme folder to a testable, exportable theme, with examples suited to a games site.

Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.

What a WordPress block theme is

WordPress introduced block themes in version 5.9. They are built primarily from blocks and a theme configuration file, and they expose the major areas of a site—including headers, footers, templates, and global styles—to the Site Editor. WordPress’s Theme Handbook describes the model in its official documentation: WordPress Developer Resources: Themes.

#	Preview	Product	Price
1		Build a WordPress Website with AI for Beginners in 2026: A Step-by-Step System to Create, Design,...	$2.99	Buy on Amazon
2		Professional WordPress: Design and Development	$25.45	Buy on Amazon
3		WordPress for Beginners 2026: A Visual Step-by-Step Guide to Mastering WordPress (Webmaster Series)	$19.99	Buy on Amazon
4		WordPress for Beginners: The Ultimate Step-by-Step Guide to Build a Website, Blog, or Online...	$11.99	Buy on Amazon
5		How To Create A Website Using Wordpress: The Beginner's Blueprint for Building a Professional...	$5.38	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

A classic theme usually relies on PHP template files such as header.php and single.php. A block theme uses HTML files containing block markup instead. WordPress renders those blocks, applies the settings and styles declared by the theme, and lets an administrator edit the result under Appearance > Editor.

Recognition does not depend on theme.json. A theme is recognized as a block theme when it contains a block-markup template such as templates/index.html or the older block-templates/index.html location. theme.json is strongly recommended because it connects your design system to both the front end and editor controls, but it is not a required recognition file.

#1 Best Overall

Build a WordPress Website with AI for Beginners in 2026: A Step-by-Step System to Create, Design, and Launch a Professional Site Without Coding Using ... Easy (Wordpress and Growth with AI Book 1)

$2.99

Buy on Amazon

The minimum file structure

Create a directory inside wp-content/themes. The smallest practical starter contains these files:

A useful starting tree looks like this:

my-game-theme/
├── style.css
├── theme.json
├── templates/
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   ├── search.html
│   └── 404.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
├── styles/
└── assets/

Prepare a safe development workflow

Use a local WordPress installation and a code editor so you can activate, break, and reset the theme without affecting a public site. Keep the theme in version control from the first file. A block theme can be edited in the Site Editor, but saving those edits directly to the database creates a second source of truth; exporting or copying the resulting files back into your project keeps the work reproducible.

1. Install WordPress locally. Create a disposable site with administrator access and enable permalinks so archives, searches, and 404 routes can be tested.
2. Open the themes directory. Add a uniquely named folder under wp-content/themes. Avoid spaces and avoid using a name that could be confused with an existing theme.
3. Study a current default block theme. The Theme Handbook’s quick-start material points beginners to Twenty Twenty-Four, Twenty Twenty-Three, or Twenty Twenty-Two. Inspect how those themes divide templates, parts, patterns, and style settings.
4. Create the three starter files. Add templates/index.html, style.css, and theme.json before adding visual polish.
5. Activate the theme. In the dashboard, go to Appearance > Themes, activate your folder, and check the front page. A syntax error in block markup usually appears immediately, which makes early testing valuable.
6. Build the shared shell. Put the site header and footer in template parts and insert those parts into the templates that need them.
7. Add page-specific templates. Create single, page, archive, search, and 404 files only when the site requires a distinct structure. A fallback template is better than a collection of unfinished files.
8. Iterate in the Site Editor. Use Appearance > Editor to test templates, styles, patterns, and parts at realistic content lengths and screen sizes.

Create the starter files

Write the theme metadata in style.css

Even when most design work lives in global styles, retain style.css for the metadata WordPress uses to list the theme and for exceptional CSS rules.

/*
Theme Name: Game Atlas Blocks
Author: Your Name
Description: A block theme for a games publication.
Version: 1.0.0
Text Domain: game-atlas-blocks
*/

The metadata comment is not a place for layout rules. Add ordinary CSS below it only for selectors that global styles cannot express, such as a special gradient effect, a legacy embed, or a carefully scoped component state.

Make a first page in templates/index.html

Templates are HTML files containing serialized blocks. A simple index template can provide a site header, a main content area, and a footer:

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:query-title {"type":"archive"} /-->
  <!-- wp:query -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:group {"layout":{"type":"constrained"}} -->
      <div class="wp-block-group">
        <!-- wp:post-title {"isLink":true} /-->
        <!-- wp:post-excerpt /-->
      </div>
      <!-- /wp:group -->
    <!-- /wp:post-template -->
    <!-- wp:query-pagination /-->
  </div>
  <!-- /wp:query -->
</div>
<!-- /wp:group -->

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

The exact block attributes can be changed in the editor. The important principle is that the file describes a complete document structure: template parts frame the page, while query and post blocks supply content.

Rank #2

Sale

Professional WordPress: Design and Development

$25.45

Buy on Amazon

Add reusable header and footer parts

Create parts/header.html with a site identity, navigation, and any utility controls:

<!-- wp:group {"align":"full","layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group alignfull">
  <!-- wp:site-logo /-->
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

Create parts/footer.html with a short description, navigation, and copyright block. Keep parts focused: a header that contains unrelated page content becomes difficult to reuse.

Understand templates, parts, and patterns

Templates describe whole views

A template answers, “What is the structure of this kind of request?” A single-post template for a review site might contain the post title, featured image, author, publication date, content, related navigation, comments, and the shared footer. A page template can omit review metadata. An archive template can lead with a heading and then repeat post cards. A search template should make the query and result count clear. A 404 template should give the visitor a useful next action instead of an empty message.

Start with the fallback index template, then add specialized files when the content model demands them. This keeps the initial theme understandable and avoids subtle differences caused by copying a large block tree into every file.

Parts hold repeated sections

Put a shared header, footer, or sidebar in parts/. Insert it with a Template Part block. When the navigation, logo treatment, or footer links change, one edit updates every template that references the part. Deliberately create separate parts when two areas really need different structures—for example, a compact article header and a larger landing-page header.

Patterns package reusable arrangements

Patterns are groups of blocks registered for insertion in the editor. They are ideal for repeatable sections such as a game-review hero, a post header with metadata, a call-to-action strip, a newsletter prompt, or a three-card “latest releases” section. A pattern is not the same as a template part: a part is a named section embedded in a template, while a pattern is a reusable block arrangement an editor can insert into content or a template.

Rank #3

WordPress for Beginners 2026: A Visual Step-by-Step Guide to Mastering WordPress (Webmaster Series)

$19.99

Buy on Amazon

Keep pattern markup self-contained and give each pattern a clear purpose. If an editor should be able to insert several independent copies, use a pattern. If the site must have one synchronized header everywhere, use a part.

Use theme.json as the design system

theme.json is the central configuration file for global settings and styles. It controls which design tools appear in the editor and supplies the values used on the front end. The schema is versioned; the current reference lists version 3 as the latest, so check the version appropriate to the WordPress installation you support rather than copying an old example unchanged.

A small configuration can establish a palette, typography choices, spacing, and a constrained content width:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "ink", "color": "#171717", "name": "Ink" },
        { "slug": "paper", "color": "#f7f5ef", "name": "Paper" },
        { "slug": "accent", "color": "#e34a3b", "name": "Accent" }
      ]
    },
    "layout": {
      "contentSize": "700px",
      "wideSize": "1100px"
    },
    "spacing": {
      "units": [ "px", "rem", "em", "vh", "vw" ]
    },
    "typography": {
      "fluid": true
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|paper",
      "text": "var:preset|color|ink"
    },
    "spacing": {
      "blockGap": "1.25rem"
    }
  }
}

The example illustrates the relationship between settings and styles. Settings expose controls and presets; styles apply the defaults. Preset references such as var:preset|color|accent keep the palette centralized instead of scattering color values through dozens of blocks.

Settings to decide early

• Color: define the approved palette and decide whether custom colors should be allowed.
• Typography: set available font families, sizes, line heights, and whether fluid typography is appropriate.
• Spacing: establish consistent padding, margin, and block-gap options.
• Layout: set content and wide widths so long-form reviews remain readable while galleries and comparison sections can expand.
• Appearance tools: expose only controls your design can support. Fewer, intentional controls reduce accidental combinations.

When custom CSS still makes sense

Use theme.json for design tokens and block-level defaults. Use custom CSS for an exceptional selector, a transition, a pseudo-element, or a third-party embed that does not expose a block setting. Keep such rules scoped and documented. If a rule is really a color, spacing value, or typography choice, move it into the global system instead of creating a one-off override.

Build a game-site template set

A games publication can demonstrate the architecture without making the theme dependent on one editorial format.

Rank #4

WordPress for Beginners: The Ultimate Step-by-Step Guide to Build a Website, Blog, or Online Business — No Coding Required

$11.99

Buy on Amazon

Single review template

Use templates/single.html for the article view. A practical order is post title, featured image, author and date metadata, the content, a post-navigation block, comments, and the footer part. Keep review-specific labels in the content or a pattern unless every post on the site is a review.

Archive template

Use templates/archive.html for category pages such as Reviews, Guides, and News. Place the archive title above a Query Loop and use a consistent card pattern inside the loop. Test categories with long names and with no posts so the heading and empty state remain useful.

Page and landing templates

Use templates/page.html for evergreen pages. A landing page assembled from patterns can be edited visually without creating a new template for every campaign. If a page needs a genuinely different document shell, create a dedicated template only when that difference is stable and intentional.

Search and 404 templates

Search visitors need a visible query heading, results, and pagination. A 404 view should explain that the requested URL was not found and offer search, the home page, or popular categories. These templates are easy to overlook because they are not the first screen you see during development, so test them explicitly.

Work in the Site Editor and export the result

With a block theme active, open Appearance > Editor. The exact controls can vary by WordPress version, but the workflow is consistent:

1. Open Design or Styles to inspect the global palette, typography, and spacing supplied by theme.json.
2. Open Templates to preview and edit index, single, page, archive, search, and 404 structures.
3. Open Patterns to create reusable compositions and to manage template parts. Since WordPress 6.3, the Site Editor can create and manage patterns and template parts when a block theme is active.
4. Edit at representative widths and with realistic titles, excerpts, featured images, and author names. A layout that works with “Test Post” may fail with a three-line game title.
5. Save deliberately. Site Editor changes can be stored as user customizations, so note which changes belong in the project files and which are intended as site-specific content.
6. Export the finished theme when you need to move it to another installation or distribute it. Exporting turns the edited templates, parts, patterns, and styles into a theme package rather than leaving them only in the current site’s database.

The first-party Create Block Theme plugin is an additional export option when you need more control over creating or exporting a block theme. Treat the exported files as source code: review them, remove accidental experiments, test on a clean installation, and put the final package under version control.

Best Value

How To Create A Website Using Wordpress: The Beginner's Blueprint for Building a Professional Website in Less Than 60 Minutes

$5.38

Buy on Amazon

Choose an implementation approach deliberately

Test before calling the theme finished

Use a checklist rather than relying on the home page alone.

• Activate the theme on a clean local site and confirm that the fallback index renders without PHP warnings or broken block markup.
• Open a single post, a static page, an archive, a search result, and a nonexistent URL.
• Check menus, site title, logo, featured images, post metadata, pagination, comments, and template parts.
• Test empty states: an archive with no posts, a search with no matches, and a post without a featured image.
• Resize the browser and inspect narrow, wide, and intermediate layouts.
• Enter long game titles, long author names, large images, nested lists, tables, quotes, and embedded media.
• Verify that the editor controls exposed by theme.json produce the intended front-end result.
• Check keyboard focus, heading order, link purpose, color contrast, and visible focus states.
• Export the theme, install that package on a second local site, and repeat the critical checks.

Common beginner problems and fixes

The theme does not appear in Appearance > Themes

Check the folder location and the metadata comment in style.css. Confirm that a block template exists at templates/index.html or the supported block-templates/index.html path. A missing or malformed metadata header can also prevent normal listing.

The editor shows a blank or broken template

Inspect the block comments for matching opening and closing markers. A missing <!-- /wp:group -->, malformed JSON in a block attribute, or ordinary HTML placed where serialized block markup is expected can break the structure. Reduce the file to one known-good group, confirm it renders, and add blocks back in small increments.

Styles appear in the editor but not on the front end

Check whether the value was saved as a user customization rather than in theme.json. Confirm that the style is attached to the block or selector you intended and that a later rule in style.css is not overriding it. Test the exported package on a clean site to distinguish a theme issue from an old saved customization.

A header change affects every page unexpectedly

That behavior is normally the point of a shared template part. If one section genuinely needs a different header, create a second part and reference it only from the templates that require the alternative.

A pattern is difficult to find or reuse

Give it one clear purpose, keep the block arrangement self-contained, and avoid turning a full page into a pattern when editors only need one section. Use template parts for globally shared structures.

A practical first project plan

1. Day one: establish the shell. Create the three starter files, add a header and footer part, and make the fallback template readable at mobile and desktop widths.
2. Day two: define the design system. Choose the palette, type scale, content width, wide width, spacing units, and editor controls in theme.json.
3. Day three: support content types. Add single, page, archive, search, and 404 templates where the site needs them.
4. Day four: create patterns. Build a review header, a game-card grid, a call-to-action, and any repeatable editorial sections.
5. Day five: test and export. Use realistic content, exercise empty and error states, export the theme, install it on a clean local site, and correct anything that depends on hidden database customizations.

The goal is not to fill every possible folder. A maintainable block theme has a small, understandable set of templates, shared parts where reuse is real, patterns for repeatable editorial layouts, and a theme.json file that makes the design system visible to both authors and the front end.

Quick Recap

Bestseller No. 1

Build a WordPress Website with AI for Beginners in 2026: A Step-by-Step System to Create, Design, and Launch a Professional Site Without Coding Using ... Easy (Wordpress and Growth with AI Book 1)

$2.99

SaleBestseller No. 2

Professional WordPress: Design and Development

$25.45

Bestseller No. 3

WordPress for Beginners 2026: A Visual Step-by-Step Guide to Mastering WordPress (Webmaster Series)

$19.99

Bestseller No. 4

WordPress for Beginners: The Ultimate Step-by-Step Guide to Build a Website, Blog, or Online Business — No Coding Required

$11.99

Bestseller No. 5

How To Create A Website Using Wordpress: The Beginner's Blueprint for Building a Professional Website in Less Than 60 Minutes

$5.38

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.