You open a theme folder, stare at a pile of files, and wonder which one actually controls the page in front of you. That confusion slows teams, breaks shipping schedules, and hurts results. The fix is simple. Get your WordPress theme structure tight, learn how the template hierarchy decides what loads, and use it to ship clean pages without hacks.
This guide shows you how to do that. We cover classic themes, block themes, template parts, and the exact load order for the most common page types. You will walk away knowing which file to create, where to put it, and how to keep your theme maintainable for the long haul.
Tell Us What You Need – Start Your Journey Today!
Share your project requirements, and we’ll guide you through a seamless development journey to bring your ideas to life.
How the WordPress Template Hierarchy Works
The template hierarchy is WordPress asking one question: what is this request? Then it walks down a list until it finds a file that matches. No match, no problem. It falls back to index.php.
Here is the big idea you will use every day:
- WordPress identifies context, for example a single post, a page, a category archive, a custom post type archive, a search result, or a 404.
- It looks for the most specific file name first.
- It keeps falling back to more generic files until it lands on index.php.
This gives you power. You can create a file that targets a narrow context without touching the rest of the site.
Classic Theme File Structure
A clean wordpress theme file structure is simple and boring, which is perfect:
my-theme/
style.css
functions.php
index.php
header.php
footer.php
sidebar.php
page.php
single.php
archive.php
search.php
404.php
partials/
card.php
hero.php
Why this works:
- style.css declares the theme and holds your theme header.
- functions.php enqueues styles and sets up theme supports.
- header.php, footer.php, sidebar.php are shared across templates.
- partials/ holds small reusable pieces. You can load them with get_template_part( ‘partials/card’ ).
Small parts keep your code dry. When design changes, you update the part once and move on.
Block Themes
Block themes move layout into HTML files and configuration into theme.json. The structure looks like this:
my-block-theme/
style.css
theme.json
functions.php
templates/
index.html
single.html
page.html
archive.html
404.html
parts/
header.html
footer.html
Why teams use block themes:
- theme.json sets design tokens in one place. Colors, spacing, typography. You control them centrally.
- templates/ and parts/ are editable in the Site Editor. Content teams can adjust layout without touching PHP.
- Patterns speed up page assembly. You build once, reuse everywhere.
If your site depends on heavy PHP logic or complex dynamic layouts, a classic theme still fits. Many teams run a hybrid: classic templates for dynamic sections, block templates for marketing pages. Either path benefits from understanding the hierarchy.
Which File Loads for Each Page Type
You do not need the full tree every day. You need the working set. Here it is, using classic PHP names first, then the block equivalents in brackets.
Single post or custom post type
Order for a single post of type book and slug dune:
- single-book-dune.php
- single-book.php
- single.php
- singular.php
- index.php
Block equivalents: single-book.html, single.html, singular.html, then index.html.
Static page
Order for a page with slug about and ID 42:
- page-about.php
- page-42.php
- page.php
- singular.php
- index.php
Block equivalents: page-about.html, page.html, then index.html.
Category archive
- category-news.php
- category.php
- archive.php
- index.php
Block equivalents: category-news.html, category.html, archive.html, index.html.
Tag archive
- tag-featured.php
- tag.php
- archive.php
- index.php
Block: tag-featured.html, tag.html, archive.html, index.html.
Custom taxonomy term
For taxonomy genre and term sci-fi:
- taxonomy-genre-sci-fi.php
- taxonomy-genre.php
- taxonomy.php
- archive.php
- index.php
Block: taxonomy-genre-sci-fi.html, taxonomy-genre.html, taxonomy.html, archive.html, index.html.
Custom post type archive
For CPT book:
- archive-book.php
- archive.php
- index.php
Block: archive-book.html, archive.html, index.html.
Author and date archives
- Author order: author-{nicename}.php → author.php → archive.php → index.php.
- Date order: date.php → archive.php → index.php.
Block: author.html or date.html, then archive.html, then index.html.
Front page and blog posts page
Two special cases that confuse teams:
- If Settings → Reading → Your homepage displays → A static page, WordPress looks for:
- front-page.php for the homepage file.
- home.php for the posts page file.
- If your homepage shows latest posts, WordPress loads home.php first, then index.php if no home.php exists.
Block equivalents follow the same logic with .html.
Search results and 404
- Search: search.php → index.php. Block: search.html → index.html.
- 404: 404.php → index.php. Block: 404.html → index.html.
These are easy wins. Add custom templates for both. You improve user paths and brand trust in one afternoon.
Examples for Common WordPress Site Scenarios
Case 1: Marketing site with a custom hero and modular cards
- Use front-page.php for the main landing page.
- Load a reusable hero with: <?php get_template_part( ‘partials/hero’ ); ?>
- For card grids on archives, move the card markup into partials/card.php and call it inside the loop with: <?php get_template_part( ‘partials/card’, get_post_type() ); ?>
Case 2: Portfolio with a custom post type
You register a CPT named project. Add:
- single-project.php for project detail pages.
- archive-project.php for the gallery.
- Optional template part partials/project-meta.php to keep details tidy.
If a single project needs a special layout, create single-project-landing.php and you target only that slug.
Case 3: Editorial site with sections
Category sections want different headers and layouts. Create:
- category-news.php
- category-guides.php
They fall back to category.php for all other categories. Your editors get tailored layouts without touching code.
How to Use Child Themes the Right Way
Use a child theme when you start from a parent you plan to update. You override only what you need, keep the rest in sync, and avoid forks that drift.
Create a folder, add style.css with a proper header:
/*
Theme Name: My Child Theme
Template: parent-theme-folder-name
Version: 1.0
*/
Enqueue styles in functions.php:
add_action(‘wp_enqueue_scripts’, function () {
$parent = ‘parent-style’;
wp_enqueue_style($parent, get_template_directory_uri() . ‘/style.css’);
wp_enqueue_style(‘child-style’, get_stylesheet_uri(), [$parent], wp_get_theme()->get(‘Version’));
});
How overrides work:
- Put single.php in the child, and WordPress uses it instead of the parent’s file.
- Add partials/hero.php in the child, and calls to get_template_part( ‘partials/hero’ ) use the child’s version.
- Keep functions unique to avoid redeclaration. Prefix your functions. Load new files using require_once in the child.
If you need a quick refresher, we have a short guide on the WordPress child theme setup that covers versioning and safe overrides.
Troubleshooting Template Selection
When WordPress serves the wrong layout, run through these:
- Confirm file names and slugs. A misspelled page-about.php never loads.
- Check the Reading settings. A static homepage changes whether front-page.php or home.php is used.
- Confirm your child theme’s Template header points to the parent folder name, not the theme name.
- Use the Template panel in the Site Editor on block themes to see which template is active.
- Drop get_queried_object() into the template to confirm context when debugging complex taxonomies.
Nine times out of ten, the issue is file naming or a Reading setting.
FAQs
How can I override the layout for one page only?
Create page-{slug}.php or page-{id}.php. That file takes priority over page.php and affects only that page.
What should I use for a CPT archive?
Use archive-{post_type}.php. Add a grid layout, custom loop, and filters there. It falls back to archive.php if not found.
Do block themes follow a hierarchy too?
Yes. The same idea applies, with .html files in templates/ and shared parts in parts/. You still have front-page.html, home.html, single.html, page.html, archive.html, and more. theme.json controls design tokens and block settings.
How do I keep shared components consistent?
Put shared markup in partials/ for classic themes and in parts/ for block themes. Call them from templates. Update once, roll across the site.
How can I tell which template WordPress is using for a page?
Use the Query Monitor or Show Current Template plugin. They show the exact file WordPress is loading. You can also echo get_page_template() while testing.
Should I create a new template file or use a pattern or block layout?
Use a pattern or block layout for visual changes only. Create a new template file when you need different logic, data, or structure.
How does theme structure affect performance and maintenance?
A clean structure cuts duplicate code, improves caching, and makes updates safer. Pure Website Design helps teams streamline themes for better speed and workflow.
When should I hire help for theme restructuring?
If your templates are messy, outdated, or inconsistent, it’s time to refactor. Pure Website Design can audit and rebuild your theme for clarity and performance.
Summary
Set up a lean wordpress theme development base. Create the core templates, wire in your partials or parts, and keep filenames specific to the context. When the structure reflects how WordPress thinks, your team ships faster, your layouts stay consistent, and your performance work becomes targeted.
If you want a partner to map and implement this for you, we can help. Pure Website Design audits your current theme, delivers a clean wordpress theme file structure, writes the right templates for your content model, and documents the exact load order your team will use every week.
