iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
A WordPress block theme is a theme built primarily from blocks and HTML templates. It lets you edit the header, footer, page layouts, styles, and reusable sections in the Site Editor instead of limiting visual changes to a Customizer or PHP files. You can start with three files—templates/index.html, style.css, and theme.json—then add templates, template parts, patterns, and optional code as your site needs them.
This guide shows how the pieces fit together, how to build a small theme safely, and when to choose the Site Editor, files, core blocks, custom blocks, global styles, or custom CSS.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches
What a WordPress block theme is
WordPress introduced block themes in version 5.9. The official Theme Handbook describes a block theme as a theme built mainly with HTML and a theme-configuration file, composed of blocks so that all major areas of a site can be edited in the Site Editor. See the WordPress Theme Handbook for the current platform documentation.
In practical terms, a block theme replaces much of the traditional PHP-template workflow with block markup. A template is an HTML file containing blocks such as the site logo, navigation, query loop, post title, content, and footer. WordPress parses that markup and renders the page. Users can then open Appearance > Editor and adjust templates, template parts, styles, and patterns through the visual interface.
A block theme can still contain CSS, JavaScript, PHP, and other assets when they are genuinely needed. “Block theme” describes the theme’s primary template and editing model; it does not prohibit every other file type.
How WordPress recognizes a block theme
A block theme must provide a block-markup template. The usual signal is templates/index.html (or the older block-templates/index.html location). theme.json is strongly recommended, but it is not required for WordPress to recognize the theme as a block theme.
Keeping this distinction in mind prevents a common setup mistake: a theme can be technically recognized without theme.json, yet you lose the central place for global settings, style presets, and editor controls. For a usable beginner theme, create all three starter files together.
The minimum starter structure
Create a directory inside your WordPress installation’s wp-content/themes folder. Give it a unique lowercase name, such as northstar-block. A minimal, maintainable structure looks like this:
| Path | Required? | Purpose |
|---|---|---|
templates/index.html |
Yes for the normal starter | Fallback document structure made from blocks. It is used when a more specific template is not selected. |
style.css |
Keep it | Theme metadata and any stylesheet rules that cannot be expressed through global styles. |
theme.json |
Recommended, not required for recognition | Global settings, design tokens, styles, layout options, and editor-facing controls. |
templates/ |
Directory | Top-level structures such as archives, single posts, pages, search results, and 404 pages. |
parts/ |
Optional directory | Reusable sections such as headers, footers, and sidebars. |
patterns/ |
Optional directory | Reusable block arrangements that WordPress can register for insertion in the editor. |
styles/ |
Optional directory | Additional style variations that users can select in the Site Editor. |
assets/ |
Optional directory | Images, scripts, fonts, or other files your theme needs. |
WordPress also supports optional PHP or JavaScript files. Add them for a specific requirement—such as enqueueing a script, registering a feature, or providing server-side behavior—not as a reflexive replacement for block markup.
What belongs in each directory
Templates describe a whole view. A single-post template may place a header, post title, featured image, metadata, content, comments, and footer in a defined order. An archive template may use a query loop to list posts. Templates should describe page structure rather than become a dumping ground for every repeated component.
Recommended Free Tools
Template parts hold sections used in more than one template. A header part can contain the site identity and navigation; a footer part can contain widgets, a copyright line, and a secondary navigation menu. Editing one part then updates every template that references it.
Rank #2
Patterns package a useful arrangement of blocks for insertion. Examples include a hero area, a post header, a call-to-action band, or a complete footer composition. A pattern is an insertion tool, while a template part is normally a named section referenced by templates.
Prepare a local development site
Use a local WordPress installation and a code editor before changing a live site. A local site gives you a safe place to activate an unfinished theme, inspect errors, and reset content while learning. Keep the theme directory under version control if you expect to make regular changes or work with another person.
Before creating files, check the WordPress version running locally and use a current default block theme as a reference. The Theme Handbook specifically points beginners toward Twenty Twenty-Four, Twenty Twenty-Three, and Twenty Twenty-Two. Comparing their templates and theme.json files shows conventions that are easy to miss when starting from an empty folder.
Free tools Windows power users keep installed
One-click scans. No signup required.
Build the first working theme
- Create the theme directory. Add
wp-content/themes/northstar-block(or your own unique name) and make thetemplates,parts, andpatternsdirectories. - Add theme metadata. Create
style.csswith a comment header containing at least the theme name. Keep the file even if your first design uses only global styles. - Create the fallback template. Add
templates/index.htmland place a basic block structure inside it. A useful first skeleton includes a template-part reference for the header, a main group containing the post or page content, and a footer template part. - Add reusable parts. Create
parts/header.htmlandparts/footer.html. Build each with core blocks such as Site Logo, Site Title, Navigation, Group, Paragraph, and Social Icons. Reference the parts from your templates instead of duplicating their markup. - Add a global configuration. Create
theme.jsonand define the palette, typography choices, spacing, layout widths, and controls that should appear in the editor. - Activate and inspect. In the WordPress dashboard, open Appearance > Themes, activate the theme, and then open Appearance > Editor. Look at the Styles, Templates, Patterns, and Template Parts areas.
- Test the fallback. View the home page, a post, a page, an archive, a search result, and a nonexistent URL. Note which view uses
index.htmland which views need their own templates.
Start with valid, simple markup. Add one block or one setting at a time, refresh the editor, and keep the last known-good version available. A small incremental loop is easier to debug than a large first import.
Designing templates with block markup
A template is a document outline. The order of blocks determines the order visitors see. Core blocks are usually the best starting point because WordPress maintains them and they remain portable across installations.
Common templates to add
| Template | Typical use | Blocks or structures to consider |
|---|---|---|
single.html |
Individual blog posts or custom post entries | Header part, post title, featured image, post date, author, content, comments, related query loop, footer part. |
page.html |
Static pages | Header part, page title, featured image when used, content, comments where appropriate, footer part. |
archive.html |
Category, tag, author, date, or custom archives | Archive title, description, query loop, pagination, and footer part. |
search.html |
Search results | Search query title, query loop, “no results” message, pagination, and footer part. |
404.html |
Missing URLs | Clear error message, search form, links to key areas, and footer part. |
Do not create every possible file on day one. Add a specific template when the fallback produces the wrong structure or when a view needs intentionally different content. This keeps the architecture understandable.
Template parts and consistency
Use one shared header and one shared footer when the site has a consistent shell. If a landing page truly needs a different header, create a separate part with a descriptive name rather than quietly copying markup into several templates. Shared parts make global changes predictable; separate parts preserve deliberate exceptions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
Using theme.json for global settings and styles
theme.json is the central design and editor configuration file. It can expose controls for colors, typography, spacing, borders, layout, and other supported features while applying the same decisions to the front end and the editor preview. The schema is versioned; the current reference lists version 3 as the latest, so check the reference that matches the WordPress version you support before choosing settings.
A small configuration might look like this:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"appearanceTools": true,
"color": {
"palette": [
{ "slug": "ink", "color": "#1f2933", "name": "Ink" },
{ "slug": "paper", "color": "#ffffff", "name": "Paper" },
{ "slug": "accent", "color": "#0f766e", "name": "Accent" }
]
},
"layout": {
"contentSize": "680px",
"wideSize": "1200px"
}
},
"styles": {
"color": {
"text": "var(--wp--preset--color--ink)",
"background": "var(--wp--preset--color--paper)"
},
"spacing": {
"blockGap": "1.5rem"
}
}
}The example is intentionally small. In a real project, validate property names against the versioned schema and add only controls you want users to change.
Settings versus styles
- Settings decide what is available: a palette, font-size presets, layout widths, appearance tools, or spacing controls.
- Styles decide the defaults: body colors, typography, block spacing, links, headings, buttons, and other supported elements.
- Presets create reusable values that produce consistent editor controls and CSS custom properties.
Use theme.json for design tokens and ordinary component styling first. Reserve custom CSS for selectors, effects, or browser behavior that the supported global-style controls cannot represent. Mixing both approaches is normal; the goal is to keep the common system centralized and understandable.
Patterns: reusable compositions without duplication
Patterns are useful when a section should be inserted in many places but does not need to be a permanent part of every page. A hero pattern can combine a heading, paragraph, image, and button. A post-header pattern can group the title, author, date, and featured image. A call-to-action pattern can be inserted into pages without rebuilding its spacing and alignment each time.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Store custom patterns in the theme’s patterns directory with the registration metadata WordPress expects. Keep patterns focused: one clear purpose, sensible defaults, and no hidden dependency on a specific page. If the same markup must update everywhere automatically, use a template part instead.
Since WordPress 6.3, the Site Editor can create and manage patterns and template parts when a block theme is active. That makes it possible to prototype visually, save the result, and later move the stable structure into the theme files if you need repeatable version-controlled output.
File-first versus Site Editor-first development
Both workflows are valid. Choose based on the kind of change you are making and how the theme will be maintained.
| Approach | Strengths | Trade-offs | Best fit |
|---|---|---|---|
| File-first | Clear diffs, repeatable builds, easy code review, and a durable source of truth. | Slower visual experimentation and a steeper initial learning curve. | Themes maintained by a team, distributed to multiple sites, or managed with version control. |
| Site Editor-first | Fast visual iteration and immediate feedback with real content. | Changes saved in the database can drift from the files and are not automatically a distributable theme package. | Exploration, client workshops, and discovering the layout before formalizing it. |
A practical compromise is to sketch in the Site Editor, identify the final structure, then copy or recreate the stable result in templates, parts, patterns, and theme.json. Keep track of which source should win when a file and a user-saved customization disagree.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchCore blocks or custom blocks?
Start with core blocks whenever they can express the requirement. They reduce maintenance, work with WordPress’s editor, and make the theme easier to move. Use a custom block when the interaction, data source, or rendering behavior cannot be delivered cleanly with core blocks and patterns.
- Choose core blocks for headings, media, navigation, query loops, buttons, columns, groups, lists, and ordinary content sections.
- Choose a pattern for a repeatable visual arrangement that editors should insert and customize.
- Choose a custom block for bespoke interactive behavior, specialized data, or a component that needs its own editing interface and rendering logic.
Every custom block adds code that must be maintained across WordPress updates and content migrations. Treat it as an architectural decision, not merely a styling shortcut.
Testing a block theme in the Site Editor
After activation, test both the editor and the public site. A layout that looks correct in one post may fail on an archive, a long title, a missing image, or a mobile viewport.
- Open Appearance > Editor > Styles and verify the palette, typography, spacing, and layout controls match your intended design.
- Open the template list and inspect the home, single, page, archive, search, and 404 views. Confirm each uses the expected parts.
- Open Patterns and Template Parts. Insert a pattern into a test page, edit a shared part, and confirm the scope of each change.
- Test navigation with a keyboard and check heading order, link text, color contrast, focus visibility, and image alternatives.
- Preview posts with short and very long titles, no featured image, many categories, comments, and no search results.
- Check narrow and wide screens. Verify content width, wide alignment, buttons, tables, navigation, and spacing do not overflow.
- Save a copy of the theme files, then export only after the result is stable.
When something is wrong, isolate the layer responsible: template markup for structure, theme.json for global settings and styles, a block’s own controls for local overrides, and custom CSS or scripts for exceptional behavior. This avoids rewriting a template to solve a color-token problem.
Exporting a theme from the Site Editor
The Site Editor is excellent for building and adjusting a theme, but a finished design saved only in a site’s database is not automatically a theme package you can distribute. Use the editor’s export capability when available, or use the first-party Create Block Theme plugin when you need additional export options.
Before exporting, review the package as code:
- Confirm the theme directory and metadata are correct.
- Check that templates reference existing parts and that no test content or accidental personal customization is included.
- Open
theme.jsonand remove obsolete settings, duplicate values, and unsupported properties for your target WordPress versions. - Test the exported copy on a separate local installation rather than assuming the original site is proof of portability.
Export is a handoff step, not a substitute for testing. If users will install the theme on different sites, keep the file-based version under version control and document the WordPress versions you support.
Common beginner problems and fixes
The theme does not appear as a block theme
Check that the theme folder is in wp-content/themes, that style.css contains valid metadata, and that a block template such as templates/index.html exists. A missing or misspelled directory name can make WordPress ignore the expected file.
The Site Editor is unavailable
Verify that the block theme is actually active. Classic themes use a different editing experience, so seeing the Customizer does not prove that your block templates loaded.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Changes in the editor do not match the files
The Site Editor can save customized templates, parts, and styles in the database. Decide whether the database customization or the theme files are authoritative, then reset or reapply the other version deliberately. Export the final state if it needs to travel to another site.
A global style does not affect one block
Inspect the block’s local settings and its assigned style variation. A local block setting can override a global default. Also confirm that the property is supported by the relevant theme.json schema version before adding CSS.
A layout breaks on unusual content
Test long headings, empty optional fields, missing images, nested groups, and translated text. Replace fixed heights with flexible sizing, set sensible content and wide widths, and keep important text in real text blocks rather than images.
Duplicated headers or footers drift apart
Move shared markup into parts/header.html or parts/footer.html and reference the part from each template. Maintain separate parts only when the difference is intentional.
A practical decision framework
Use these questions when deciding how to implement a feature:
- Is it the structure of an entire view? Put it in a template such as
single.htmlorarchive.html. - Does the same section appear across views? Make it a template part.
- Should editors insert it into selected content? Make it a pattern.
- Is the value part of the design system? Define it in
theme.jsonas a setting, preset, or style. - Does the behavior require custom editing or rendering logic? Consider a custom block or a small plugin rather than forcing the theme to do application work.
- Will the behavior need to survive a theme switch? Put site functionality in a plugin where appropriate; keep the theme focused on presentation.
Beginner checklist
- Use a local WordPress site and a code editor.
- Study a current default block theme before inventing your own conventions.
- Create
templates/index.html,style.css, andtheme.json. - Build a header and footer as reusable template parts.
- Add only the specific templates your content requires.
- Use patterns for repeatable insertable compositions.
- Put design tokens and editor controls in
theme.json. - Prefer core blocks until a custom block is justified.
- Test editor and front-end behavior with realistic content and screen sizes.
- Export and test a clean copy before distributing the theme.
What to remember
Block-theme development is a division of responsibilities: templates define page structure, parts define shared sections, patterns define reusable insertions, and theme.json defines the design system and editor controls. The Site Editor makes visual work fast, while files provide a repeatable foundation for maintenance and distribution.
Begin with the smallest working theme, verify each layer in the editor and on the front end, and add complexity only when a concrete requirement demands it. That approach gives beginners a theme they can understand now and extend without losing control later.
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.
