So You Think You Know How to Write a WordPress Theme?

By Kerry Butters

In this article, we’ll get you started on WordPress theme development, dealing with what you need to learn before you even think about coding.

WordPress has become the most popular CMS in the world. As of May 2013, is was used by 52% of the top blogs across the globe, according to a survey carried out by Technorati and Pingdom. This is an increase of 4% over 2012, so it’s clear that the platform continues to rise in popularity.

WordPress usage stats

There are over 65 million WordPress sites in use and, as mentioned, that number continues to grow. So for developers, there’s a clear opportunity to carve out a niche for making WordPress themes and create a valuable addition to their skill set.

Getting Started

In theory, it’s easy to make a theme and it’s something that is getting even simpler as time goes on and support gets better. All you really need to begin is an index.php file and a style.css file—but this won’t make you stand out from the crowd. And if you’re going to venture into learning a new skill, then you might as well do it to the best of your ability, right?

Before we go any further, if you want to make a great theme, then it’s necessary to have a good working knowledge of HTML and CSS, preferably with experience of coding HTML5 and CSS3. It’s a competitive market and WordPress supports both of these new standards.

If it turns out you have no knowledge of the new standards, you can get up to speed by taking a look at the Jump Start HTML5 series on Learnable or HTML5 & CSS3 for the Real World published by SitePoint.

It’s also necessary to understand that your theme will have to be compatible with the latest version of WordPress and perhaps some legacy versions too, as not everyone upgrades to the latest straight away, due to potential compatibility issues. Because everyone’s set up is different, compatibility issues may not affect everyone, so it may depend on what themes and plugins are installed on the site, or even on the server setup.

The WordPress Marketplace

WordPress coding standards are pretty strict; security is a must and it’s necessary to look into licensing, popular plugins, and the WordPress APIs before making a start on the coding side of things. In other words, do your homework. Don’t assume that because you can code, that’s all you’re going to need. It’s also worth giving some thought to how well you will be able to support the theme.

Will you have the time to:

  • Create updates and patches
  • Respond to customer queries and issues with their installation
  • Maintain the theme and continue development
  • Include code comments, which are vital to creating a theme

Take a look at the documentation on the WordPress site before getting started, so you’ll be aware of exactly what you’re getting into. Anyone can become a WordPress developer, but it’s a rigorous process if you want to get the theme approved and entered into the official theme directory.

Also, have a good look through WordPress’s coding standards to ensure that you really are up to the task before. This could help you avoid much frustration later on.

Preparing Yourself

Now that you know what you’re getting into, and assuming you’ve prepared so far by brushing up on necessary coding standards, take a look around at the structure of some really good existing themes.

Themeforest are currently billing a theme called ‘X’ as being the best out there. It’s quite complex, but worth taking a look. The best place to start, however, is with the current default Twenty Fourteen theme (which is one of three themes bundled with WordPress 3.8) to get a good overview of the basic WordPress structure.

You’ll be working with about 12 core files when you begin the build process. These include:

  • header.php
  • index.php
  • sidebar.php
  • footer.php
  • archive.php (for categories, posts, authors, dates and so on)
  • single.php (individual posts)
  • comments.php
  • page.php (for static pages rather than posts)
  • search.php
  • 404.php
  • style.css
  • functions.php (allows changing of core functionality without editing core files)

Most of the above are self-explanatory for those that have developed a site in the past. There are also a series of PHP template tags that you insert into your code, allowing for dynamic content. When in doubt, refer to the codex to see how tags work and which are suitable for what you want to achieve.

Doing it Right

If you don’t follow WordPress’s submission guidelines, your theme will not be accepted. One requirement is that you don’t spell WordPress in any other way than I have. It seems a small requirement, but it’s an important one; no lower case P, no laziness, it has to be spelled that way and that’s that or it won’t be accepted.

While I mentioned backwards compatibility earlier, this must be minimised to one major previous version. The current version is 3.8, so that means that you shouldn’t go back beyond 3.7 when it comes to making your theme compatible with previous versions.

It’s also vital that your coding is clean and error-free. There must be no "_doing_it_wrong()" notices, errors relating to .php, or JavaScript errors. It’s also recommended to validate HTML and CSS (though validation-free code is not expected; the default Twenty Fourteen theme for example has 23 CSS validation errors). For more information check out out the code quality guidelines.

WordPress APIs

If you’re going to write a WordPress theme, then it’s an excellent idea to learn the APIs inside out. There are plenty of them and they are separated into sections and topics and cover the functions that are involved and necessary to build a theme.

Mostly, you’ll be concentrating on the following:

  • Options
  • Settings
  • Theme customization
  • Shortcodes
  • Widgets

However, there are literally tons more, so you should take a look at each of them and decide what you need before you begin to build the theme.

What’s Next?

Now that you know some of what’s involved before you even get started building a theme, the next step is to look into languages, licensing, and structure. Or you could just get on with the coding and get a taste for it to see for sure if it’s something you would like to carry on with first. ## Alternative Resources

If you want to create a theme but don’t want to go through the hassle of learning the ins and outs of the codex, APIs, and compatibility issues, then you can always ‘cheat’. There are a few sites that allow you to build your own theme without going to a huge amount of trouble. These include Ultimatum, which is a drag and drop builder that you can use without any coding knowledge. It does of course come at a price, namely $65 for a starter license and £125 for Pro (lifetime) membership—so there are other options open to you if you find it too challenging trying to code your own theme.

Next Time

In a future article we’ll look at code structure in more detail, submission processes, what to do if your theme is rejected, and language support. There’s so much involved when it comes to building a theme that if you want to compete, you need to build a great one. Later on we’ll also take a closer look at resources that can help you build and test your theme and more.

Update: The article was updated to remove reference to a possible permissions issue with WordPress 3.8, as this was not correct.

  • > it’s necessary to have a good working knowledge of HTML and CSS,
    > preferably with experience of coding HTML5 and CSS3. It’s a competitive
    > market and WordPress supports both of these new standards.

    Actually HTML5 & CSS3 are browser based technologies and have nothing to do with WordPress. You can create your whole theme in XML & style it with CSS or XSLT and WordPress won’t care one bit & it’ll still work. :)

    > For example, the latest version, 3.8, is known to have issues surrounding
    > permissions, so many people are sticking with 3.7.1 for the time being

    I’ll assume you didn’t read through that thread which you linked. The issue that person had turned out to be file permissions related on her server, not WordPress related.

    > Anyone can sign up to be a WordPress developer

    You don’t need to signup to be a WordPress developer. You need to signup at if you want to add your theme or plugin to the official WordPress repository. Otherwise you can distribute your stuff on your own, there are no restrictions or compulsions.

  • Themes created with generators are not accepted by

  • Great tips, Kerry.

    I’ve been meaning to create some minimal WordPress themes, just don’t have the time at the moment :)

  • LouisLazaris

    Amit Gupta

    Thanks for your comment. It was actually marked as spam, and that’s why it took so long to get it on here. It absolutely was not intentional. We have no problem publishing critical comments. In fact, I encourage polite criticism, as that’s always good for readers.

    Your point about the 3.8 permissions issues was correct. I’ve made an edit to update that section and remove the link to that thread. Thanks for pointing that out.

    I also improved the wording regarding ‘signing up’ for theme development. I don’t think it was that big of a deal, but you’re right, we don’t want to give the impression that you can’t do it outside of the official directory.

    You also said:

    Actually HTML5 & CSS3 are browser based technologies and have nothing to do with WordPress. You can create your whole theme in XML & style it with CSS or XSLT and WordPress won’t care one bit & it’ll still work.

    Sorry but that might be the most technically over-pedantic thing I’ve ever read. :) To say that HTML and CSS, in this day and age, have “nothing to do with WordPress” is, in the strictest technical sense, absolutely right. But that is completely beside the point. There is no relevant niche for non-HTML WP themes. That’s just not an issue. Therefore, Kerry’s advice stands, and it’s very good advice. Anyone who doesn’t know HTML and CSS is not going to have much success in WP theme development.

    • For the HTML5/CSS3, I said it in context of:

      It’s a competitive market and WordPress supports both of these new standards

      Its not for WordPress to support these, WordPress has nothing to do with these & thats what I commented on. Its the way that part is worded gives the in-correct impression to a newbie that HTML5/CSS3 support is dependant on WordPress.

      • LouisLazaris


        Fair enough. The way she worded it wasn’t the best, but remember that much of the SitePoint audience is beginners, so clarifying that they can use CSS3 and HTML5 in WP themes isn’t a bad thing. I think she just shouldn’t have used the word “support”.

  • Marcel van der Hoek

    Great article, got some actionable tips out of it.

    One remark: the link to the theme called ‘X’ on ThemeForest points to a Page Not Found.

Get the latest in WordPress, once a week, for free.