Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 68 ยท Classic Themes and the Template Hierarchy

Your First Classic Theme

Build a minimal classic WordPress theme - the style.css header, index.php, header.php and footer.php, wp_head and wp_footer, body_class and add_theme_support basics.

A WordPress theme is a folder inside wp-content/themes/ that controls how your site looks. A classic theme is made of PHP template files and a stylesheet. It takes only two files to make a valid theme, style.css and index.php, and a handful more to make a useful one. In this lesson you will write a small but complete theme: the stylesheet header, the main template, a header and a footer, and a functions.php that switches on a few features.

Before you start, you should know how the template hierarchy picks files and how the Loop works. Everything here is real WordPress code shown in read-only blocks. The runnable examples are plain-PHP stand-ins that assemble the page the way WordPress does, so you can see the order of the pieces.

The theme folder

Create a folder wp-content/themes/notebook/ and put these files in it:

TEXT
notebook/
  style.css       required: the theme header and your CSS
  index.php       required: the fallback template
  header.php      the top of every page
  footer.php      the bottom of every page
  functions.php   theme setup and features

The folder name is the theme's identifier, so use lowercase letters and hyphens. WordPress lists every folder that has a valid style.css header under Appearance, Themes.

style.css and its header

The first lines of style.css are a PHP-style comment that WordPress reads as data. Only Theme Name is strictly required, but fill in the rest, because the admin shows them and the theme directory expects them:

CSS
/*
Theme Name:   Notebook
Theme URI:    https://example.com/notebook
Author:       Your Name
Description:  A tiny classic theme for learning.
Version:      1.0.0
Requires at least: 6.0
Requires PHP: 8.1
License:      GNU General Public License v2 or later
License URI:  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  notebook
*/

body {
    font-family: system-ui, sans-serif;
    max-width: 42rem;
    margin: 0 auto;
    padding: 1rem;
}

After the header, the file is ordinary CSS. WordPress does not load it automatically on the front end. You enqueue it from functions.php, as shown below. Text Domain is used for translations, which you will meet in testing and deployment.

index.php, header.php and footer.php

index.php is the template that always exists. It calls two helper functions to pull in the shared header and footer, and it contains the Loop:

PHP
<?php get_header(); ?>

<main>
    <?php if ( have_posts() ) : ?>
        <?php while ( have_posts() ) : the_post(); ?>
            <article <?php post_class(); ?>>
                <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
                <?php the_excerpt(); ?>
            </article>
        <?php endwhile; ?>

        <?php the_posts_pagination(); ?>
    <?php else : ?>
        <p>Nothing found.</p>
    <?php endif; ?>
</main>

<?php get_footer(); ?>

get_header() includes header.php and get_footer() includes footer.php. Here is a header:

PHP
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

<header>
    <h1><a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a></h1>
    <p><?php bloginfo( 'description' ); ?></p>
</header>

And the matching footer:

PHP
<footer>
    <p>&copy; <?php echo esc_html( wp_date( 'Y' ) ); ?> <?php bloginfo( 'name' ); ?></p>
</footer>

<?php wp_footer(); ?>
</body>
</html>

Three calls in these files are not optional decoration:

  • wp_head() just before </head>. This is where WordPress prints the title tag, your enqueued stylesheets, scripts, the emoji and block styles, SEO plugin tags and much more. A theme without it loses all of that.
  • wp_footer() just before </body>. Scripts that load in the footer, the admin bar for logged-in users and many plugins depend on it.
  • body_class() prints a class attribute full of useful names such as home, single, single-post, logged-in and page-id-12. It lets your CSS target a type of page without any template changes.

Forget wp_head() or wp_footer() and plugins will mysteriously stop working, so check for them first when something is missing.

flowchart TD
    A["index.php"] --> B["get_header()"]
    B --> H["header.php<br/>wp_head(), body_class()"]
    A --> L["The Loop<br/>the_title(), the_excerpt()"]
    A --> C["get_footer()"]
    C --> F["footer.php<br/>wp_footer()"]
    H --> P["Finished HTML page"]
    L --> P
    F --> P

One template pulls in the header and footer around its own Loop, and the three parts form the page.

Assembling a page

Here is a stand-in that builds the page in the same order as the real files. wp_head() and wp_footer() run registered callbacks, and get_header() and get_footer() print strings. This is not WordPress, but the order of events is the same.

PHP Assembling a page from header, Loop and footer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Look at where each callback's output landed. The <title> and stylesheet appear inside <head> because they were registered for wp_head, and the script appears before </body> because it was registered for wp_footer. That is the whole idea behind these two calls: they are hook points, and the theme and plugins attach output to them.

functions.php

functions.php is loaded on every request, before the template. Use it to register features and attach callbacks to hooks. Start with theme support and enqueue the stylesheet:

PHP
<?php
add_action( 'after_setup_theme', 'notebook_setup' );

function notebook_setup(): void {
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'html5', [
        'search-form', 'comment-form', 'comment-list', 'gallery', 'caption', 'style', 'script',
    ] );
}

add_action( 'wp_enqueue_scripts', 'notebook_assets' );

function notebook_assets(): void {
    wp_enqueue_style(
        'notebook-style',
        get_stylesheet_uri(),
        [],
        wp_get_theme()->get( 'Version' )
    );
}

What the three features do:

  • title-tag lets WordPress print the page <title>. With it, you do not write a <title> element in header.php; WordPress adds one through wp_head().
  • post-thumbnails enables featured images, so the_post_thumbnail() works and editors see the Featured image box. Images get their own lesson, images, thumbnails and media.
  • html5 makes core output modern markup for the listed features, for example <form> and <figure> elements instead of older markup.

Two details are easy to get wrong. First, add_theme_support() belongs in a callback on after_setup_theme, not at the top level of the file. Second, stylesheets and scripts are enqueued with wp_enqueue_scripts, never hardcoded as <link> tags in header.php; see enqueuing styles and scripts. The hooks themselves are explained in actions and filters.

PHP Reading a theme header and theme support

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The real get_file_data() function reads headers in a similar way, and the real body_class() produces many more names. The stand-in only shows the principle: the header is plain text that WordPress parses, and feature flags are checked before core does optional work.

Activate and test

  1. Put the folder in wp-content/themes/.
  2. In wp-admin go to Appearance, Themes and activate Notebook.
  3. Visit the site. You should see your posts listed with a pagination block when there are enough of them.
  4. Turn on WP_DEBUG while developing (see debugging WordPress) so a typo shows an error rather than a blank page.

From here, add the files from the hierarchy as you need them: single.php for single posts, page.php for pages, archive.php for archives, search.php and 404.php. Split repeating pieces into template parts, covered in template parts and template tags.

Common mistakes

  • Missing wp_head() or wp_footer(). Styles, scripts, the admin bar and plugins silently fail.
  • A blank line or space before <?php in functions.php. It can break redirects and feeds because output starts too early.
  • Calling add_theme_support() too early or too late. Use after_setup_theme.
  • Hardcoding the stylesheet link. Enqueue it, so versioning, dependencies and child themes work.
  • Editing a theme downloaded from the directory directly. Updates overwrite your changes. Use a child theme for that, which comes later in this track.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two files are required to make a valid classic theme?

    style.css carries the theme header that WordPress reads, and index.php is the final fallback template. Everything else is optional.
  2. 2. Why must a theme call wp_head() before </head>?

    wp_head() fires the hook that prints the title tag, stylesheets, scripts and other head output. Without it, much of that content is missing.
  3. 3. What does add_theme_support( 'title-tag' ) do?

    With title-tag support, WordPress outputs the document title through wp_head().
  4. 4. Where should add_theme_support() be called?

    Theme features are registered on after_setup_theme, which runs on every request after the theme loads.

Summary

  • A classic theme is a folder in wp-content/themes/; style.css (with a header comment) and index.php are required.
  • get_header() and get_footer() include header.php and footer.php; the template's Loop prints the content.
  • wp_head(), wp_footer() and body_class() are essential: they are the hook points for plugins, styles, scripts and CSS targeting.
  • functions.php registers features on after_setup_theme (title-tag, post-thumbnails, html5) and enqueues assets on wp_enqueue_scripts.
  • Activate the theme in Appearance, Themes, then add more templates from the hierarchy as you need them.
  • The runnable examples are plain-PHP stand-ins; the theme files shown are real WordPress code.

Next: Template Parts and Template Tags