WordPress Theme development is a popular way of building WordPress sites for clients or for your own business if you’re into selling themes. But when starting out, it’s hard to choose how to approach it and what to read, learn or watch. In this guide, I’ll try to guide you into developing WordPress themes.

Before trying to do any developing with WordPress, you need to have a server and WordPress installed on it. I have tried several tools for local development that allow you have a working server (not public). If you are a beginner or just a developer who wants to immediately start developing without worrying about setting WordPress properly, you should try Local by Flywheel.

I have a video on that topic which you can watch here.

WordPress Basics

If you’re into WordPress theme development, you need to learn about some of the basic concepts in WordPress. Once you understand the basics, you can develop themes much easier. And also, you can then know what to look or search for in google 🙂


You can start a custom WordPress theme with only 2 files: index.php and style.css. That’s all you need. And you probably already know about that. So what are some other files you should try out? Maybe some, but several should be used:

  • header.php and footer.php – templates to be used for header and footer of your page
  • single.php – Template for all single posts (or post types)
    • single-$post_type-$slug – Template that targets a specific post type ($post_type is the post type of the post and the $slug is the post name of the post
  • page.php – Template for single pages (A page slug/id can be also added to it to target specific pages)
  • attachment.php – Template for attachments
  • 404.php – Template to be used when there is no content found
  • home.php – Template used to display blog posts
  • front-page.php – Template used for the first page of the site
  • archive.php – Template for displaying an archive (can be also specified with a custom post type slug)
  • taxonomy-$type.php – Similar to archive.php but for specific taxonomies

You can also have custom templates, and I would advise always to name them template-something.php with the word template being always the first one. To learn more about template files, you should check the Theme Handbook.

Each file that is used to display a page or post or some other content, should also have the function get_header() at the beginning and the function get_footer() at the end of the file. If you want to have a specific header or footer, you can pass a string to those functions. For example, if you pass a string new and have a file header-new.php, that file will be used for the header. If it doesn’t exist, WordPress will use the default header.php. That’s what WordPress template hierarchy is.

Template Hierarchy

WordPress always tries to load a template you want and default to index.php as the last resort. So, if you’re on a single post, WordPress will try to find:

  • single-$id – ID of the single post
  • single-$posttype-$slug – Slug of the single post or post type
  • single.php
  • singular.php
  • index.php

That’s the reason why index.php is a file that must be included in your theme. To learn more on how that can help you in WordPress Theme development, you should check the Template Hierarchy.

Template Tags & The Loop

Template tags are actually functions which you can use in or even (some) outside of the loop. There are a lot of template tags and the complete list can be found here.

For example, the template tag to display the title of the current post inside the loop is the_title(). This will immediately use the current post’s ID and display it on the page. If you don’t want to display it but just return it to a variable, you could use get_the_title().


The WordPress loop is a while loop that goes over the main WordPress query which queries the database for posts based on criteria provided on the page. If the page is a single post, the loop will have only that one post. If it’s an archive and we are on page 2, the loop will show X number of posts (where X is the number set in the settings of WordPress) and it will also offset the posts so that the loop shows posts that are meant to be on the second page.

How does the Loop look like?

You can learn more about the WordPress loop here.

Theme Functionality

In WordPress Theme development, it is known that some themes will have some specific functionalities. The file that WordPress loads from a theme is functions.php. This file will be used to include theme specific functions. You can always have a inc folder to have more files and include those files inside the functions.php.

Some of the stuff you should put there are:

  • Theme Setup function
  • Register Theme Sidebars
  • Register Theme Menu Locations
  • Define what does the theme support
  • Include scripts & styles

Example: Theme Setup

To start a theme setup you need to have a custom function that you would hook into the action after_setup_theme:

By hooking our function inside that action, we are sure that everything will load correctly after the theme has been fully loaded. As you can see in the code example, after the theme has been fully loaded, we are then registering our menu locations.

You can learn more about the Theme Functions here.

Styles & Scripts

A standard way to include styles & scripts in the WordPress theme development, is to enqueue them. You should NOT add them directly to the header or footer of the theme.

So, how to enqueue them? We will use the hook wp_enqueue_scripts.

To learn more about linking CSS & JavaScript, be sure to check it out here.

The main style file style.css needs to have the Theme definition.


Sidebars are places we register in our theme and then we can add widgets to them. Sidebars are defined inside the functions.php.

To register a sidebar, you will have to use the function register_sidebar() and that function should be hook inside the action widgets_init.

When registering a sidebar, you need to define some parameters inside an array:

  • name – Name that will appear inside Appearance > Widgets
  • id – id of the sidebar that you’ll put as a parameter inside the function dynamic_sidebar
  • description – provide more info about that sidebar
  • class – class to be added on the admin side if you want to style it a bit. Won’t be used on the front.
  • before_widget – HTML that will be used before the widget
  • after_widget – HTML that will be used after the widget
  • before_title – HTML that will be placed before the widget’s title
  • after_title – HTML that will be placed after the widget’s title

How to use the Sidebar?

When you want to use a sidebar, then you can use the function get_sidebar(). By doing that, you will be able to call the sidebar in several places such as in files single.php and page.php. To use it, we need to pass a string inside that function:

That function will now look for a file named sidebar-main.php. To show our sidebar in that file, we need to place something like this:

This will look if our sidebar has any widgets and if it has, it will load them.

Beware of the Theme Lock-in Effect

With WordPress theme development, you have to be careful with dividing theme & functionality. The so-called Theme Lock-in effect is the scenario where you provide a lot of functionality which is then lost when your user activates another theme.

Let’s look at a simple scenario:

Your theme has a post type Events. The user of your theme inserts a lot of events. But then after some time, he/she decides to use another theme to help them with their events business. But as those events were defined inside the previous theme, all that data is not visible anymore.

The events, that were inserted into the database, are left there, but the new theme does not know about them and how they were registered, so they do not show up on that new theme.

To avoid that, those events should have been defined inside a separate plugin.

WordPress Starter Themes

WordPress theme development became a little easier with starter themes. Starter themes are basic themes that you can use to built your theme upon it. Many of such themes include basic style definitions, several files such as single.phparchive.php or other and also provide several functions inside the functions.php.

Here is a list of some of them:

  • _s (Underscores) – a theme that I also use when building a theme. It has defined functions that you can use in your theme and a nice folder structure you could follow as you go along
  • UnderStrap  – a underscores theme based on Bootstrap 4 to immediately provide you with a responsive layout
  • Sage – a more advanced theme which has other tools inside such as gulp and bower to help you speed up your workflow

If you’re just starting out, I can suggest you to start working with underscores.

Child Themes

Child Themes are something that can also help you with your WordPress theme development. Such themes are actually dependant on a parent theme. That means that if you’re going to build a child theme for Divi, your theme will need the Divi theme to be installed.

Also when doing that, your child theme will inherit everything from the parent theme. That is a nice way if you have to change a theme but still, want to be sure that an update won’t delete all your changes.

To make a child theme, you need to have a new definition inside the style.css of the child theme and that is the Template. The value is the slug of the parent theme.

Including the Parent Theme Stylesheet

Many of child themes are using the css @import to get the stylesheet of the parent theme. If you are serious with WordPress theme development, I would not recommend that approach.

Why? Even if that is put inside a CSS file, it will load another file. Since in the WordPress theme development handbook, you can learn how to enqueue styles and scripts, I would use that. So instead of a CSS import just use another wp_enqueue_style.

Here is an example on how you can enqueue the style from the parent theme:

The function get_template_directory_uri()  is always using the parent theme URL. To get an URL to your child theme, you should use the function get_stylesheet_directory_uri(). That function will always return the URL to yoru current active theme.

Theme Testing

When you’re done with your theme, you need to test your theme. To make the WordPress theme development a bit easier, you already have a solution for that.

There are two ways to test your theme and I think you should always go through both.

The first one is to import the test data. You can download it from the Theme Testing Page. This will import a lot of pages & posts with images & galleries. You can then go through each and fix the styles that needs to be fixed.

You will probably have to fix some of the PHP code also.

The other way is to go through manual steps which can be found on the Codex.

WordPress Theme Development Tutorials

So, now you are equipped with some knowledge about WordPress Theme Development. But, when I started, I like to read a lot of tutorials (or watch them) on the same topic.

Here is a list of some:

If you want some premium videos on building themes & plugins, you can check out my own WordPress Development course: Become a WordPress Developer.

Become a Sponsor

Posted by Igor Benic

Web Developer who mainly uses WordPress for projects. Working on various project through Codeable & Toptal. Author of several ebooks at https://leanpub.com/u/igorbenic.


  1. I looked at the WordPress Template Hierarchy (https://developer.wordpress.org/files/2014/10/wp-hierarchy.png) and I did not see two things that you mentioned. Maybe the image is out of sync with the WordPress code.

    single-about.php – it looks like to use $slug it has to be single-$type-$slug.php
    single-$id – I don’t see this mentioned


    1. Hi Damien, yes that is correct. It seems I was thinking about the page template. You can use such thing with page.php versions. If you want to actually check all the possible versions for each template, you can check the file wp-includes/template.php.


  2. Hey! This guide was super useful for me, I think you really know what you’re doing and how to explain it to the community =) So I wanted to say Thank You before I go back to work on my wordpress!


  3. Thank you so much, this was so simple and clear…


Leave a reply

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

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