How to create a WordPress theme from scratch (I)

The intuitive WordPress has become the most popular CMS (Content Management System), both by individuals and by companies. The fact that this platform is used in 25% of the Internet websites certify its undeniable popularity, and at the same time helps to understand why developers not using WordPress are wasting a huge opportunity.

Although there are a lot of causes that explain the success and its acceptation grade, some of the main reasons are the simplicity, flexibility and power that it offers to the developers when they have to create themes or plugins. Because of this, some developers say that despite they work with a CMS, they have the feeling that nothing is impossible to do.

Before starting to develop our theme, I recommend to make a new naked WordPress installation in a remote or local server. This is because in order to test our theme, we need to have it active.

In this post I’ll assume that you know how to install and configure a WordPress site, that you know how to access your server via FTP, and that you know HTML, CSS and have some notions of PHP.

Create a new Theme

As you may know, WordPress installs all themes in the themes directory, located inside the wp-content folder:


To begin to develop our theme, we can create a new folder with any name we want (don’t use special characters or spaces). However, keep in mind that to add a new directory inside themes doesn’t make WordPress understand that there exists a new theme to use. To offset this problem, we need at least two new files.

  • index.php
    It’s the file that WordPress calls if it can’t find any homepage template. Also it’s a required file in the root of your theme directory.
  • styles.css
    Besides being the main file to define the theme styles, it’s also the file where we will specify the theme main parameters.


At the moment, we have the minimum required files for WordPress to detect a new theme. If we open the Theme Manager in our WordPress installation we’ll see something like this:


Notice that when we see something like this, it’s because WordPress has already detected our new theme.

Next we’ll improve the Theme Manager preview, to make it more attractive to potential users.

Customize the Theme Manager Preview

Now is the moment to open our style.css file and add, in comment format, some parameters at the top of the document. It’s very important to keep exactly the same structure that we show below, so that WordPress doesn’t have problems in understanding the parameters.

After this action, in the WordPress Theme Manager we’ll see something like this:


In this example only some of the possible parameters are defined (you can find the full set of options here).

Our advice is that you don’t only copy and paste the code: try to write it, change the parameters, put a cool name to your template, test and change the parameters… and check what happens in every situation. Additionally, we encourage you to continue these suggestions in any step we take. Dare to experiment without fear!

In order to complete our theme preview in the Theme Manager, we need to add a screenshot of the theme final look. As our theme consists on a white page, we’ll add a default image to illustrate this step.

This image should be renamed as screenshot, of 800x660px and preferably has to be in .png format (although .jpg, .jpeg or .gif are also valid formats). Moreover, it has to be placed inside the root directory of our theme, at the same level of the index.php and style.css files.


Now, our theme has a better look in the Theme Manager, right?



Additional Theme files

The next step is to add the rest of the files that we’ll use throughout this tutorial. All these files have their name defined by WordPress:

  • header.php
    This file is used to define the header that will be common throughout the theme navigation. For example, it can contain the main navigation menu as well as the contents inside the <head> tag.
  • footer.php
    Like the header.php file, this file will be common for all our theme. It’s used to indicate the information that is always in the footer of the page (for example the copyright or the legal information links).
  • sidebar.php
    This file was created to show a sidebar, specially for blogs or to contain widgets as a search engine, a category list or the most viewed posts.
  • home.php
    This is the template that WordPress loads as a default home page. This file is intended to be a post listing, as a blog front page.
  • front-page.php
    This template is the one that WordPress shows when the option “Show Static Page” as a home page is active. This file is intended for cases when the home page is a static page, like a corporative homepage.
  • single.php
    It is the template that shows a complete post by default.
  • page.php
    This template shows a page by default, whenever there is no other template specified in the page editor.
  • category.php
    This template will be used to show a post listing of a specific category.
  • comments.php
    It’s the template that we’ll call inside of single.php to add support to comments to our posts.
  • search.php
    It is the template that WordPress shows when it carries out a search.
  • 404.php
    It the template that WordPress shows when links are broken or don’t work.
  • functions.php
    This file will allow us to create menu and widget zones, and customize some parameters that WordPress bring by default.

After creating these files, the directory of our theme must to be like this:


Note that we have just created these files, and are empty. Therefore, they do nothing by themselves. They simply are the files that WordPress will look for depending on each situation. Some of these files, for example the header.php, the footer.php or the sidebar.php, have to be added manually inside other templates.

Great! we already have the needed structure to create a functional theme in WordPress. The last step that we need to do is leave the theme active. It will be a white page, but this way we can start to see all our progresses that we are doing.

You can see the original post in spanish here.

See you at the next post!

Jordi Cuenca

When I was fourteen I read a book named “Learning to travel around the Internet”, which had a little HTML introduction in the last two chapters. These twenty-four pages changed my life forever. From that day, I never stopped working and learning about my two vocations, web developing and graphic design. As a front-end developer, I have specialized in Wordpress developing, web architecture and the design at the service of usability.


Please, add +Marina Mele in your comments. This way I will get a notification email and I will answer you as soon as possible! :-)