Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →A WordPress block theme is built primarily from blocks and HTML templates, with a theme.json file controlling global settings and styles. Once a block theme is active, the Site Editor can reach the header, footer, templates, styles, patterns, and other major parts of the site—not only the page content.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
The smallest practical starter has three files: templates/index.html, style.css, and theme.json. You can create those files in a local WordPress installation, build the layout with core blocks, refine design tokens in theme.json, test everything in Appearance > Editor, and export the finished theme when it is ready to distribute.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What a WordPress block theme is
WordPress introduced block themes with WordPress 5.9. Unlike a classic theme, which normally relies on PHP template files and a customizer-driven workflow, a block theme describes site structure mainly with block markup. The Site Editor can therefore expose the whole site structure for visual editing.
WordPress describes a block theme as a theme available from version 5.9 that is built mainly with HTML and a theme configuration file. Its parts are composed of blocks, allowing all major site areas to be edited in the Site Editor. The official Theme Handbook is the authoritative starting point: WordPress Developer Resources: Themes.
A theme is recognized as a block theme when it contains a block template such as templates/index.html or the older block-templates/index.html location. theme.json is strongly recommended, but it is not required for recognition. In practice, you should still include it because it centralizes design settings and connects those settings to editor controls.
What you need before you start
- A local WordPress installation. A local site gives you a safe place to activate an unfinished theme, reset content, and test changes without affecting a public website.
- A code editor. You will edit HTML block markup, JSON, CSS, and occasionally PHP or JavaScript.
- A current WordPress test site. Block-theme behavior and
theme.jsoncapabilities evolve, so test with the WordPress version you intend to support. - A reference theme. The Theme Handbook recommends studying a current default block theme such as Twenty Twenty-Four, Twenty Twenty-Three, or Twenty Twenty-Two before designing an architecture from nothing.
- Basic block knowledge. You should recognize common blocks such as Group, Row, Stack, Navigation, Site Logo, Query Loop, Post Title, Post Content, and Template Part.
The minimum file structure
Create a directory for your theme inside wp-content/themes/. A minimal starter can look like this:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11my-block-theme/
├── style.css
├── theme.json
└── templates/
└── index.html| Location | Purpose | Required? |
|---|---|---|
templates/index.html |
Fallback document structure made from blocks. It provides the basic output when a more specific template is not available. | Yes for a minimal block-theme starter; a block template must exist for recognition. |
style.css |
Theme metadata and any stylesheet rules that cannot be expressed through global styles. | Keep it in the theme even when most styling is handled elsewhere. |
theme.json |
Global settings, color palette, typography, spacing, layout controls, and style values shared by the editor and front end. | Recommended, but not required for block-theme recognition. |
templates/ |
Top-level page structures such as archives, single posts, pages, search results, and 404 pages. | Directory is optional; add templates as your site needs them. |
parts/ |
Reusable sections such as headers, footers, and sidebars. | Optional. |
patterns/ |
Reusable groups of blocks that WordPress can register for insertion from the editor. | Optional. |
styles/ |
Additional style variations that users can select in the editor. | Optional. |
assets/ |
Images, fonts, scripts, or other supporting files. | Optional. |
| PHP or JavaScript files | Behavior that cannot be delivered by block markup and configuration alone. | Optional; use only when the theme actually needs it. |
What belongs in style.css
WordPress reads the comment header in style.css to identify the theme. A minimal header is enough to make the theme appear in the Themes screen:
/*
Theme Name: My Block Theme
Author: Your Name
Description: A learning block theme.
Version: 1.0.0
*/You can add ordinary CSS below the header for exceptional selectors, animations, or effects. Do not use custom CSS for every color, font size, and spacing value: those decisions are better represented as global settings and styles in theme.json, where the editor can expose them consistently.
Build a block theme step by step
1. Create and activate the local site
Install WordPress locally, create a test site, and log in as an administrator. Open the Themes screen and confirm that your development directory is visible. Keep a second, known-good block theme available so you can switch back if a malformed template prevents the Site Editor from loading.
Rank #2
2. Study a default block theme
Open one of the current default block themes and inspect its templates, parts, patterns, and theme.json files. Notice how a header is represented as a Template Part, how a Query Loop assembles post listings, and how spacing and color values are named instead of repeated throughout every template. This is faster than guessing the block markup syntax.
3. Add the three starter files
Create style.css, theme.json, and templates/index.html. The exact schema for theme.json is versioned; the current reference lists version 3 as the latest schema. Start with a valid, small file and add settings gradually rather than copying a large configuration you cannot diagnose.
A basic template can use core blocks and block comments. The comments are how WordPress serializes blocks in an HTML template:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<!-- wp:query-title {"type":"archive"} /-->
<!-- wp:query -->
<!-- wp:post-template -->
<!-- wp:post-title {"isLink":true} /-->
<!-- wp:post-excerpt /-->
<!-- /wp:post-template -->
<!-- /wp:query -->
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->The example assumes that header.html and footer.html exist in parts/. If they do not, remove those Template Part blocks temporarily or create the corresponding files first.
4. Add reusable header and footer parts
Create parts/header.html for the site identity and navigation, and parts/footer.html for copyright text, secondary links, or a footer navigation. A part is a reusable section: changing it once updates every template that references it. Use a separate part when a section is shared; keep markup inside a template when a page type intentionally needs a different structure.
Rank #3
5. Add templates for real content types
Use the fallback index template only as a starting point. Add specific templates as the site requires them:
single.htmlfor individual posts.page.htmlfor pages.archive.htmlfor category, tag, author, date, or custom archive views.search.htmlfor search results.404.htmlfor missing URLs.
Keep the page skeleton in the template and use blocks such as Post Title, Post Date, Featured Image, Post Content, Comments, Query Loop, and Pagination for dynamic content. The same header and footer parts can surround each structure.
6. Turn repeated sections into patterns
Patterns are reusable arrangements of blocks. Put a hero section, post header, call-to-action, pricing layout, or newsletter section in patterns/ when users should be able to insert it from the editor. A pattern is not the same as a Template Part: a pattern is normally inserted as a starting arrangement, while a part remains a shared section referenced by templates.
7. Configure design in theme.json
theme.json is the central design contract between your theme and the editor. Use it to define the settings that users may control and the styles that should apply consistently.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches- Settings: enable or disable editor controls, define a color palette, register font families and sizes, configure spacing options, and choose layout features.
- Styles: set defaults for the body, headings, links, buttons, blocks, colors, typography, borders, and spacing.
- Layout: establish content and wide widths so Group, Post Content, and other layout-aware blocks align predictably.
- Editor-facing controls: decide which options appear in the sidebar. Limiting controls can protect a design system; enabling them can give site owners more flexibility.
Keep tokens meaningful and reusable. A named palette color such as a primary, surface, or muted value is easier to maintain than a different hexadecimal value copied into dozens of blocks. After each change, validate the JSON syntax and reload both the editor and the front end.
8. Test in the Site Editor
Activate the theme, then open Appearance > Editor. Check the main areas in this order:
- Templates: open the index, single, page, archive, search, and 404 templates you created. Confirm that dynamic blocks show real content and that the fallback template does not unexpectedly override a specific one.
- Template Parts: edit the header and footer independently. Confirm that a change appears everywhere those parts are used.
- Styles: inspect typography, colors, layout widths, and spacing. Check the editor preview and a logged-out front-end view because editor UI and front-end output can reveal different problems.
- Patterns: insert each pattern into a test page, replace placeholder content, and verify that it remains useful when repeated.
- Responsive views: test narrow and wide screens, long titles, missing featured images, empty search results, and posts with unusually long paragraphs or embeds.
9. Export the finished theme
Site Editor changes are useful during visual iteration, but a distributable theme still needs an export step. Use the Site Editor’s export option when available, or use the first-party Create Block Theme plugin when you need its additional export choices. Inspect the resulting ZIP before installing it elsewhere: confirm that templates, parts, patterns, theme.json, style.css, and any assets are present, then activate the package on a clean test site.
How templates, parts, and patterns fit together
| Concept | Scope | Best use |
|---|---|---|
| Template | Defines an entire document structure for a request such as a post, page, archive, search result, or 404 response. | Use for page-type layout and dynamic content placement. |
| Template Part | Defines a section shared by multiple templates. | Use for headers, footers, sidebars, and other site-wide structures. |
| Pattern | Provides an insertable arrangement of blocks. | Use for repeatable editorial sections that users may insert and customize. |
This separation prevents two common maintenance problems: duplicating a header in every template and turning every reusable design into a permanently linked section when editors actually need independent copies.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choosing an implementation approach
| Decision | Option A | Option B | Trade-off |
|---|---|---|---|
| Where to begin | File-first | Site Editor-first | File-first favors version-control clarity and repeatability; Site Editor-first is faster for visual iteration. |
| Block strategy | Core blocks | Custom blocks | Core blocks generally reduce maintenance and improve portability; custom blocks are justified for bespoke interaction or rendering. |
| Styling | theme.json |
Custom CSS | theme.json integrates with editor controls and centralizes design tokens; CSS handles exceptional selectors and effects. |
| Shared structure | Template Parts | Duplicated markup | Parts provide one-change consistency; duplication is appropriate only when page structures are intentionally different. |
| Starting point | Default block theme | Blank theme | A default theme offers a working reference and faster learning; a blank theme gives maximum architectural control. |
Common problems and practical fixes
The theme does not appear as a block theme
Check that the theme directory is in wp-content/themes/, that style.css has a valid theme header, and that a block template exists at templates/index.html or block-templates/index.html. A missing or malformed template can prevent recognition. theme.json alone does not make a theme a block theme.
The Site Editor shows a blank or broken template
Inspect block comments for mismatched opening and closing markers, invalid JSON attributes, and references to missing Template Parts. Reduce the template to a Group and a single visible block, confirm it loads, and then add sections back one at a time.
Changes in the editor do not match the files
The Site Editor can save customized templates and parts in the database. Those user customizations may take precedence over the copies in the theme directory. Reset the customized template or test with a fresh site when you need to verify the file version, then export the result if it is meant to become part of the distributed theme.
Styles work in the editor but not on the front end
Check whether the value is a supported theme.json setting, whether a block has its own style variation, and whether custom CSS selectors are specific enough. Test while logged out and clear any page or browser cache before diagnosing a stale result.
A layout breaks at narrow widths
Use layout-aware Group, Row, and Stack blocks, set sensible content and wide widths, and test long labels rather than relying only on a desktop screenshot. Navigation, columns, images, and buttons need explicit checks at narrow widths.
What to remember when planning the theme
- Block themes are available from WordPress 5.9 and make major site areas editable in the Site Editor.
- The practical minimal starter is
templates/index.html,style.css, andtheme.json. - Templates describe whole page structures, Template Parts hold shared sections, and Patterns package insertable block arrangements.
theme.jsonis the main home for global settings and styles and affects both editor controls and front-end presentation.- Site Editor work can be exported when you need a theme package for another site or for distribution.
Frequently Asked Questions
Do I need PHP to build a basic block theme?
No. A basic block theme can be built mainly with HTML block markup, CSS metadata and rules, and theme.json. Add PHP or JavaScript only when the theme needs behavior that blocks and configuration cannot provide.
Can I start entirely in the Site Editor and export later?
Yes. The Site Editor is suitable for visual iteration, and you can export the result when it is ready. Keep a clean test site and inspect the exported package so database customizations, templates, parts, patterns, and assets are included as intended.
Which WordPress version should a beginner use?
Use a current WordPress installation for development, while remembering that block themes became available in WordPress 5.9. Match your testing version to the version you plan to support because the theme.json schema and editor capabilities are versioned.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Is a custom block always better than a core block?
No. Core blocks usually provide lower maintenance and better portability. Build a custom block when the required interaction or rendering cannot be achieved cleanly with core blocks and theme configuration.
Quick Recap
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.
