WordPress Theme Development: Starter theme

In this tutorial we’ll focus on WordPress Theme Development: Starter theme. This will be a completely new theme that only needs the WordPress core files to work. The result will be a basic theme that can be used as the start for a custom theme.

In this tutorial we start with a static web page consisting of an ‘index.html’ (and a ‘style.css’ file) – both of which you can download – and convert this into a working WordPress theme. This theme will not be linked to a parent theme but is a stand alone WordPress theme that only needs the WordPress core to function.

Most (WordPress) blogs consist of a header section, a main section that displays the posts, a sidebar and a footer. Our html structure (see image below) will also consist of these four sections.

simple layout with header, main section, sidebar and footer

At the end of this tutorial we will break up tht php-file that we created by converting ‘index.html’ into the same four building blocks. Although we could just use a ‘style.css’ and an ‘index.php’ we will split up ‘index.php’ to show you how to do this when developing a WordPress theme.

HTML structure

Since this tutorial is not meant to learn how to create an hmtl structure I will show you the completed ‘index.html’. Later on I will refer to the line numbers shown here when I explain where you should convert code into php. Remember that I will be referring to the line numbers as they are shown here (which might differ from those in the file you are working on!).

Here I just want to point out that when you create an HTML file that you later on want to convert to WordPress files you need to focus on the code that creates the web page’s structure and not on the content. When the theme is activated WordPress will display the content from the database.

You can download ‘index.html’ (and the accompanying ‘style.css’) by clicking on the button below:


A WordPress theme needs a ‘style.css’. And as explained in the first WordPress Theme Development tutorial the ‘style.css’ must begin with the information that WordPress needs to identify the theme.

You can replace the details in the comment section of ‘style.css’ into those that are relevant for you(r theme). Vital is that WordPress can find the Theme Name. Because this is a new and independent theme there is no reference to a template (as in the ‘style.css’ of a Child Theme).

Since this tutorial is not about learning how to style a theme I simply provide the styling. Most of the styling is shown below (the ‘style.css’ in the download contains some additional styling but nothing that is really important for the goal of this tutorial).

Now that we have the html- and css-file we can start converting it into a WordPress theme.

Create a folder for the files that you will use and create in this tutorial. The name of the folder should be the same as the name of your theme (but without capital letters or spaces: e.g. the folder name for the Twenty Eleven theme is twentyeleven). You should also create a folder ‘images’ inside your theme folder. Insert the image file ‘arches.jpg’ (that I included in the download) in the images folder.

At the end of this tutorial when the theme is finished you can upload the theme folder to the themes folder in the ‘wp-content’ directory.

Add a theme screenshot

Remember when you activate a new theme that there were thumbnail versions of the themes in your Appearance tab? You’ll want a thumbnail of your own design. It has to be a PNG file and with the name screenshot.png. Just do the following:
  • Open ‘index.html’ in your browser.
  • Make a screenshot of the web page.
  • Use an image editor like Photoshop to change this image into an image with a width of 300px and a height of 225px.
  • Save the image for web as a PNG-8 file.
  • Name your file screenshot.png, and save it in your theme folder.
For your convenience I included a ‘screenshot.png’ in the download file.

WordPress theme

To convert ‘index.html’ into a working php-file we will the (dummy) content by functions that will spit out your real content.

Before delving into the index-file we start by renaming ‘index.html’ into ‘index.php’. Keep a copy of ‘index.html’ just in case something breaks and you need to return to it. Your theme folder should now contain both ‘index.html’ and ‘index.php’ (besides ‘style.css’ and ‘screenshot.png’ and the images folder).

We will now continue working in ‘index.php’.

We’ll start with the header section.

The Header

Let’s start with the title. You’ll want WordPress to be able to place your blog’s name in the title bar of your browser. WordPress needs a proper title in order to validate your theme. So replace your dummy title (in line 5) with the bloginfo tag:

The next thing is the stylesheet. WordPress provides a function that knows where your stylesheet is located. Replace the code that calls in the stylesheet (style.css) in your index.php file (line 6) with this:

Using this function instead of a hardcoded call to the stylesheet will come in handy if you ever have a need to rename your theme folder. And if somebody else will use your theme later on on a different PC (or if you upload it to a server) WordPress will still be able to locate the stylesheet (as long as it’s in the theme folder).

Add the following line right before the closing tag (which you can find in line 7):

The wp_head() is the one really important piece of code in the head: it kicks of WordPress. Without it, no WordPress.

This tag is a so-called hook. It allows developers to add elements (e.g. javascripts, styles, etc.) to the head section. Even if you develop the theme for yourself and have no intention of adding scripts etc. it’s necessary. Always insert wp_head() just before the closing tag of your theme.

Now add the body_class() function to the body tag, so it looks like this:

This function gives the bodyelement different default classes. These classes can later be called upon to add styles. If you want to know more about which classes can be called upon when you use this tag in your theme go to function reference – body class.

Next, you can replace your dummy blog title and dummy blog description with the following two tags:

These tags pull information from where you set the blog name (= Site title) and description (= Tagline) in the dashboard, and you can simply change them there ( Settings -> General).

Finally, if you want to link the blog title in the header to the homepage of the blog so visitors can jump to the home page by clicking on the blog title, use the following for the URL:

The combination of the 3 tags shown above to replace content in ‘index.php’ (lines 13 and 14) should result in:

Are you wondering why you should bother with some of this when you could have just typed your blog title, URL, and description to the theme? One reason is that if you ever want to change your blog’s title, you can just do it in one quick step in the dashboard and it will change all over your site. The other reason is that if you want to share your theme with others, you’ll need to give them the ability to easily change the name through their dashboard. Keep in mind, anything, anything at all, that will change from site to site based on the site’s purpose and content, should not be hard-coded into the theme but should be coded to be dynamically generated.

We now turn to the menu. WordPress can automatically generate a linked list of pages for you which will act as the menu. Just replace the whole “ul” part (lines 18 – 22):

– inside the nav-section – by the necessary php-function(s), so it will look like this:

What’s this code saying? First, it checks to see if the wp_nav_menu() function exists. It was added in WordPress 3.0, so some older installations might not have it. If that function doesn’t exist, the code calls an older function (‘wp_list_pages’) that lists pages.

In both functions you can see ‘depth=1’. This tells WordPress to not print (= display) a greater menu-depth than 1. If you have a menu with more (sub)levels you can set this to 2 or 3.

Since WordPress 3.0 the menu doesn’t automatically display a link to the home page anymore. I prefer having a link to the home page in the menu. That’s why I added the parameter ‘show_home=1’ to the wp_nav_menu function. When setting multiple parameters for a function (e.g. for the wp_nav_menu) the ampersand (&) has seperate them.

The Loop

We now turn to the Loop. We already explained about the basic arguments in the loop in the previous WordPress Theme Development post. So you should recognize important parts of it. The code below will replace lines 27-32 as shown above in ‘index.html’. So you have to replace those line between the article-tags with this:

This provides us with a basic loop. First the loop checks if there are posts to display. For each post it will then get the ID of the post and it will output the correct CSS classes for that post.

Each post then sits in a div. This div can be styles with the use of the post-ID and a bunch of CSS classes that were added automatically by WordPress.

For each post the loop will then:

If you prefer to display the content of the post instead of the excerpt replace ‘the_excerpt’ by ‘the_content’.

Below each post its categories, tags and info about comments will be displayed.

In the comment section you can see that there are three arguments passed, separated by commas:

  • The first option tells WordPress the text that it has to display when there are no comments.
  • The second option tells WordPress the text that it has to display when there is just one comment.
  • The third option tells WordPress text that it has to display for more than one comment. The percent symbol (%) gets replaced with the actual number of existing comments.

To provide navigation links to older and newer posts (as well as the possibility of an error message) you need to add the code below between then endwhile and the endif tags of the loop:

If you prefer other texts for the navigation than ‘Older Entries’ and ‘Newer Entries’ you can replace those labels in the code above.

If no posts are found we want WordPress to display a searchbox that the visitor can use to find what he/she is looking for.

Now that we have completed the Loop we can turn our attention to the sidebar.

The Sidebar

In the sidebar we replace the form lines (36-38) with a tag to get the searchform. And we replace the list items under Categories (41 -42) and under Archives (46 – 47) with the appropriate tags to display the category list and archive list respectively. The result should look like this:

For the categories tag ‘title_li=’ is used. This is done to turn of the default title. We already have a heading for the categories in our markup so we don’t want the default title to show up as well.

The Footer

We add the same code to the footer for displaying the home URL and blog title as we did in the header:

The really important template tag here is wp_footer(). This piece of code tells WordPress that everything is done and it can stop running now. You also need is for plugins to hook into.

This template tag should be placed just before the closing body tag.

You can now save your ‘index.php’. Copy your theme folder and past it inside the themes folder. Then start up WordPress. Go to dashboard -> appearance -> themes. Look for your theme and activate it. It should look something like this:

Screenshot showing header, two posts and sidebar

Breaking it up

A WordPress theme is composed of several template files. This allows the different parts of the site to have different functions. We will now break up ‘index.php’ into four different template files. Breaking the index.php file into template files allows us to not only share some common parts of the design, but also have different code in the different parts. the On a website the header and footer are probably shared by all pages, the content in the main column will be different from page to page. Also, you may want the sidebar on some pages, but not on others.

We’re going to break up the index.php file by removing some of the code into three new files:

  • header.php
  • footer.php
  • sidebar.php

What remains afterwards in ‘index.php’ will be supplemented with include tags (get_header, get_footer, etc.) to call for these 3 template files.


First, cut out the entire top of your index.php file. Put your cursor behind these two lines of code:

Then, cut all the way to the top of the file and paste this text into a new file named ‘header.php’ that you save within your theme folder.

Now at the very top of the ‘index.php’ file (that is, where you just cut the header text from) insert this include tag:

This is a WordPress function that includes the ‘header.php’ file you just created. If you save everything and reload your website now, nothing should have changed. Your theme displays the same as before the breaking up.


The next step is to create ‘footer.php’. Go to the beginning of the line after the sidebar div. This line contains the ‘clear: both’. Cut from the beginning of this line all the way to the end of the file after tag. Paste this into a new file and call this file ‘footer.php’. Save this file in the theme folder.

Insert this tag in at the end of the remaining ‘index.php’ to replace what you cut out:

Save ‘index.php’ and check if your theme is still working correctly.


We now only need to cut the part for ‘sidebar.php’. This is the part that starts with:

and ends with:

Cut these lines and paste them into a new file which must be named ‘sidebar.php’. Save this file as well in the theme folder.
Insert the following tag where you cut out the sidebar lines:

Save ‘index.php’.


The four template files that you just created can be used as a complete theme. However we can do better by adding one more file. When you click on the title of a post you expect WordPress to show only that post. When you click on the title of a post WordPress first checks if there is a file ‘single.php’ in the theme folder. If not it will default to ‘index.php’. But we created a loop in ‘index.php’ that shows only the excerpt of the post.
Creating a ‘single.php’ is very easy. Open ‘index.php’ and save it as ‘single.php’ without making any changes yet. Now that the theme folder contains both files we make some changes to ‘single.php’.

Firstly, the post title doesn’t need to be linked anymore. Change the following piece of code:

into this code:

Then go to the line with and replace this with:

Cut out lines 13-16 with the navigation div.
Insert these lines

of code directly below:

We do not need the error message in single.php. Delete the following piece of code:

Then go to line 10 and attach the class “single” to the post. The result should look like this:

Save ‘single.php’.

We added the class “single” to the single posts because we need to style the navigation from one single post to the next. At the bottom of ‘style.css’ add these styles:

Save ‘style.css’.

You have now created 5 template files which (together with ‘style.css’) form the building blocks of your (first?) WordPress theme. Congratulations!

You can download the template files etc. by clicking on the button below:

Add your comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.