Faragiri

Learn Themes WordPress

The fallback list WordPress walks for each kind of page, the two theme formats and the one directory listing that tells them apart, and the file that is actually running.

4Sections
3Min read
5Depth

One URL, five candidates

The order WordPress tries files for a single post

The first file that exists wins and the rest are never consulted, which is why adding a file changes the design and editing the wrong one changes nothing.

  1. single-{post_type}-{slug}.phpOne specific post. Invisible the moment the slug changes
  2. single-{post_type}.phpEvery post of one type. The useful override
  3. single.phpEvery single post of any type
  4. singular.phpShared with pages. The file most themes should have
  5. index.phpAlways exists, because a theme without it is not a theme

A block theme walks the same list with .html files in a templates directory. The rail is the hierarchy, not the file format, which is why tutorials about one kind mostly apply to the other.

WordPress picks a template file by trying a list in order and taking the
first one that exists. For a single post the list is
single-{post_type}-{slug}.php, then
single-{post_type}.php, then single.php, then
singular.php, then index.php. Nothing routes and
nothing is registered: the file's name is the routing.

Which means index.php is the only file a theme genuinely
requires, alongside style.css for the header comment that names it.
Every other file is an override that intercepts the list earlier, and adding one
is how you make one post type look different without touching anything that
already works.

The lists worth knowing by heart

  • A page: {custom}.php from the page's own template setting,
    then page-{slug}.php, page-{id}.php,
    page.php, singular.php, index.php
  • An archive: archive-{post_type}.php, then
    archive.php, then index.php
  • A missing page: 404.php, then index.php
  • singular.php is the shared fallback for a single post and a
    page, and it is the file most themes should have and do not

The slug and id variants at the top are the escape hatch, and they are worth
using sparingly: a template named after one page's slug is invisible until
somebody renames the page, at which point the design silently reverts.

Two more facts finish the model. A template file is included, not called, so
everything in scope at that point is available: $post, the query,
and anything a plugin set up on an earlier hook. And the loop is explicit rather
than implicit, which is why a template that forgets
the_post() renders the same post repeatedly or nothing at all.

The parts a template pulls in are separate files reached with
get_header(), get_footer() and
get_template_part('content', get_post_type()). That third one takes
the same fallback approach one level down, looking for
content-post.php and settling for content.php, which
is how a theme stays short without any of its files knowing about the
others.

Two kinds of theme, and how to tell in one look

A classic theme is PHP templates plus functions.php, and the
hierarchy above is the whole routing model. A block theme is HTML files in a
templates/ directory plus a theme.json, edited in the
site editor rather than in a file, and the hierarchy still applies with
.html in place of .php.

The tell takes one directory listing: theme.json and
templates/index.html present means a block theme; only
index.php and functions.php means classic. The theme
running this measurement is classic, with index.php,
functions.php and style.css present and no
theme.json. Most published tutorials are about one kind without
saying which.

What to run in 2026

A child theme is the tool when the theme is somebody else's, free with
WordPress: a directory with a style.css naming the parent and a
functions.php, and any template file you add overrides the parent's
version of it. It replaced editing the parent, which is undone by the next
update, and it is the single most useful WordPress convention.

Query Monitor names the template that was actually used for the current
request, free and open source, which turns the list above into an observation.
It replaced adding an echo to each candidate file to find out which one is
running, and it also names the parent or child directory it came from.

Where this stalls people

The stall is editing a file that is not the one being used. A change to
single.php does nothing because a single-post.php
exists, or because the theme is a child and the file being edited is the
parent's. Nothing errors, the change simply has no effect, and the natural
response is to make a bigger change.

Before editing anything, read which template is in use for that URL. It is
one line in Query Monitor and it removes the entire class of problem. What the
templates are calling into is
hooks, filters and
writing your own
, the language they are written in is
syntax, requests and the shape
of a script
, and the platform underneath is
what runs a large share of the
web
.

Alongside this

Above this