How to save time and stress when building your first WordPress theme

If you have some PHP knowledge and a good understanding of HTML, CSS and JavaScript, building a custom WordPress theme should be fairly straightforward.  That said, there a few things  I have found over time that might help.   This is not a tutorial, but hopefully it will save you some pain.

1.   Read the WordPress  documentation

I know we all hate reading manuals, but this is still the best source of information.    A little time spent in research will be less time in development later.   The documentation is a little dry, but it will give you the background in standards and hierarchy.  If you write to the standards WordPress updates are a lot less likely to cause you unexpected issues or even break your website.

If you really hate reading the documentation then at least look for a good tutorial to give you insight into the pitfalls.   Sitepoint do a good one:

Watch: Create a Bare-bones WordPress Theme from Scratch

2.  Learn the anatomy of a template and the inheritance and precedence of the files.

Certain files  will override others if they exist in your theme.  Concentrate on learning the structure of the files and the inheritance  as them affect  posts, pages, archives and your home page.   If you understand which files take prescience over others, you will be able to problem solve, when your  pages or posts are not displaying in the way you would expect.

Yoast do a great info-graphic  on this:

The anatomy of a WordPress theme


3.   Consider using a bare bones framework or starter theme

If you are a real newbie then a starter theme or framework is a good way to learn good practice.   I’m a big fan of Underscore.   With solid standards and folder structures,it allows you to build a complicated and customisable theme, that will make sense to you have in  a years time.  They even have a generator to create the bare bones of your first theme.


4.  Enqueue Scripts and Styles in your function file.

It will be tempting to  just insert references to your scripts and styles in your header or footer files.  Don’t do it.   Enqueuing them properly in your function file will save you time and frustration.  You are basically telling WordPress what you are loading and will reduce load times and conflicts.

There is a great article about this on  WPbeginner.

5.   Use the template tags to reference your theme directories.

While you can put in an absolute url’s, when referencing images or includes, don’t do it.   Reference the template directory, using the template tags, so that your theme works whatever domain it is installed on.

<?php include( get_template_directory() . '/includes/myfile.php'); ?>

6.  Turn on WordPress error reporting to debug before making your theme live.

By turning on the error reporting in WordPress while you are developing your theme in a test environment, you will pick up any errors in your code.     These errors might not stop your theme from working, but they could cause bugs and conflicts later on.    It is best to get rid of any errors before you use the your theme on a live website.

You can do this by adding the following lines to your wp-config.php file

// define('WP_DEBUG', false);

define(‘WP_DEBUG’, true);
define(‘WP_DEBUG_LOG’, true);
define(‘WP_DEBUG_DISPLAY’, false);
@ini_set(‘display_errors’, 0);

Just remember to comment them out, or delete them, before moving your website to a live environment.


7. Test your theme with real content and WordPress plugins

Before you put your new theme on a live website be sure you have tested with real content and a few Plugins.   This is your chance to find out if your code will brak when introduced to outside forces that you have less control over.

8.  Learn about version control

Even if you are working alone version control is a life safer.  While it might seem intimidating at first Git is amazingly easy to set up.  As you log each change with comments you will create an easy to follow development history.  The ability to roll back code to a previous version is a life saver and can save you hours or days of coding if your changes completely break your code.

Want to learn more I recommend  David Demaree’s book  Git for Humans    There is also a good article on  Sitepoint:  Git for Beginners

9.  And finally read the WordPress  documentation

Yes I know, but be honest, you were going to ignore that one.