Creating a WordPress Theme from Scratch: Content and the WordPress Template Hierarchy

In this second part of our guide to creating your own WordPress theme from scratch, we’ll look at content types and how you can display them in your theme. We’ll look at the WordPress Template Hierarchy and the WordPress Loop. Do you have a WordPress development environment ready on your computer? If not, follow this […]

This article was posted by Independent Software, a website and database application development company based in Maputo, Mozambique. Our website offers regular write-ups on technical and design issues, ranging from details at code level to 3D Studio Max rendering. Read more about Independent Software's philosophy, or get in touch with Independent Software.

In this second part of our guide to creating your own WordPress theme from scratch, we’ll look at content types and how you can display them in your theme. We’ll look at the WordPress Template Hierarchy and the WordPress Loop.

Do you have a WordPress development environment ready on your computer? If not, follow this easy step-by-step guide to setup IIS, PHP, MySQL and WordPress, all on your Windows computer.

This is the second part of our guide to Creating a WordPress Theme from Scratch. Start with Theme files, styles, header and footer if you’re following along.

Posts, pages and templates

In the previous section of this guide, we created the minimum required theme files, defined some CSS styles and added a header and footer. Now it’s time to put this framework to use and show some content created in WordPress.

WordPress content comes in several flavors:

  • Posts – Block of content with a date attached to it (a news item)
  • Pages – Undated block of content (a static page)
  • Custom Post Type – Block of content with a date, and additional fields defined (in code) by you

Though WordPress was originally created as a content management system for blogs, as illustrated by the core presence of the “post” content type, today it’s suitable for creating website of any type – even sites without a blog section at all. The Custom Post Types (CPTs) can be used to create any sort of content block: a movie review, a recipe, a game solution and so on.

Whenever a visitor accesses a URL on your website, WordPress services some content. The files present in your theme define how this content is presented. These presentation files are written and PHP and known as template files. So far, we have created only index.php, which will serve as the home page, but we can create single-post.php (for displaying an individual post) and page.php (for a page) as well. Actually, index.php is used only if no other template is available.

The WordPress template hierarchy

The order in which WordPress looks for and uses templates is called the template hierarchy. You can study an interactive version of it at For instance, if WordPress needs to serve a static page, it will look for the following files, in order:

  • php where custom is the name of the template used by the static page (a template can be set in the WordPress page editor)
  • page-slug.php where slug is the slug of the page WordPress wants to display
  • page-id.php where id is the unique id of the page WordPress wants to display
  • page.php
  • singular.php
  • index.php

If you look at the hierarchy diagram, you will see that singular.php also applies to posts, and index.php applies to everything: it is the final fallback template.

To create a general template for static page content, we can thus define page.php to affect all pages except for those with a specific template selected in the WordPress page editor (we’ll get to that bit later).

Creating test content

For testing purposes, we’ll need a page to display. To create one, go into the WordPress administration panel and find Pages -> Add New to create a new page. Alternatively, you can use the pre-existing “Sample Page” for testing if you’re starting with a fresh WordPress installation.

If you visit http://mydirectory/sample-page in your browser now, with the theme files we’ve created in the previous guide, you’ll get the contents of index.php again and no page content is shown. We’re about to change that.

WordPress index.php

Create a new file called “page.php” in the theme directory:

Refresh your browser, and voilá: This is a page appears. WordPress has loaded our page.php template because it is serving a static page.

Showing page content

At this point, we’re showing content that’s hard-coded in page.php and not the actual content of the page. We’ll remedy that now:

With this code in page.php, our sample page content will be properly displayed:

Our WordPress theme displays a static page

What happens here?

  • I’ve added some elements for styling. The whole page is wrapped by a div, so is the content area, and there is a <main>  block for the page content. The page content is served in an <article>  element, with a <header>  element for the page title. We can use all of this later for our CSS rules.
  • The page content is found by executing a WordPress content loop. For the moment, know that this results in the page being found and set as “the current post”. (Under the hood, everything in WordPress is called a “post”).
  • With the current post set, we use  the_title  to display the page title where we want it.  the_title  takes arguments of HTML content to be inserted before and after the title text.
  • We use  the_content  to display the page contents.
  • We use  wp_link_pages  to display page links for paginated posts. This, too, takes arguments of content to be displayed before and after the page links.

The Loop

And so we come to the core of displaying content with WordPress: The Loop. Almost every template file you write will contain an instance of The Loop. Within the loop, WordPress finds all posts that must be displayed for the current request. If the current request is the home page, WordPress might find the most recent 8 news items. If it’s a post archive page for February, WordPress might find the 18 posts you wrote in that month. If it’s a request for a single, static page – identified by its slug in the URL – WordPress will find only one post that matches, but it’s still necessary to include The Loop.

Many WordPress function may only be called inside The Loop, where WordPress is guaranteed to have set a current post to be processed. Examples are the_ID , the_title  and the_content  as used in the code above.

The Loop always starts like this:

And ends like this:

Note that we left out the “Sorry, no posts matched…” bit in our code, since a single page is guaranteed to be found.


In this guide, we have seen:

  • How to WordPress Template Hierarchy works
  • How to create a template for a static page
  • How to display static page content in our page template
  • How “The Loop” works in WordPress

In the next part of this guide, we’ll improve the styling of our template and show how you can add a main menu to your theme. Thanks for reading!

Did this article help you out? Please help us find more time to write useful guides & articles like this by donating a buck or two. It'll keep us coffee-fueled. Thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *