When I first started to create custom WordPress themes, I have to admit, I was a little confused.

I had done custom web development before, so surely WordPress would be a cake walk.

I was wrong.

I learned there was a huge difference between being a “WordPress Developer” and a WordPress Developer.

I truly had no understanding of the WordPress architecture and the conventions of the framework.

The good news is, I’ve gone through all of the pain and frustration so you don’t have to!

If you can learn the following concepts, you will be a WordPress theme creating master in no time!

Disclaimer: This article makes the assumption that you already have some PHP, CSS, and HTML experience and also know how to install WordPress on a local development machine.

wp_contents Directory

For custom WordPress development, the wp_contents directory is pretty much where you will be spending all of your time.

This folder houses all of your themes and plugins.

There are 3 main folders you will be concerned with when first starting out:

• themes – this will hold the majority of your code. Think of it almost as the “root directory” of your theme.
• plugins – this is where all of the wonderful (and extremely convenient) WordPress plugins get installed. You can also develop your own plugins within this folder.
• mu-plugins – this is where you want to store plugins that will always be available, regardless of installed theme.

Once you understand this architecture, you’re ready to start making your very first custom theme!

Importance of a Naming Convention

Ok, so now we’ve got “the lay of the land”, how do we start making our custom theme?

Hold your horses young Padawan! We must first set ourselves up for success.

Here’s a word of advice, I recommend you come up with a naming convention now. Since WordPress makes up approximately 40% of the internet, there’s a decent chance many “common” names have been taken.

I made this mistake with one of the very first themes I created. I named the theme “corporate”, not knowing what I know now about naming conventions.

To make a long story short… There is already a “corporate” theme out there (shocker) that receives fairly regular updates. In the WordPress “Appearance” dashboard, if you were to click “update theme”, my custom theme would be overwritten by the “corporate” theme that was made by another developer.

This same problem can happen with variables, functions, and classes.

I find the best approach is creating a naming convention. If you’ve never heard that term before, it basically means a standardized pattern in how you name everything.

So for us, since we are “EJ Web Design”, any file or function we can freely name (more about this later), we do so with “ejwd{name of variable or function}”. This significantly lowers the chance of unintentionally choosing a name that another developer has already used.

I know this is kind of annoying, but a little annoyance now will save you big headaches down the road.

Custom Theme File Structure

Now that we have a naming convention in mind, we are going to put it to use immediately.

We first need to go into the “themes” directory, create a folder and give it a name (using our naming convention, of course).

For demonstration purposes, let’s say we are doing a website for Carl’s Computers. I would name the theme directory, “ejwd_carls_computers”, or your favorite flavor of casing and spacing.

Within that folder we have several MUST HAVE files that we will create ( I typically create these in the command line to save time, but using your code editor will do just fine):

• style.css
• functions.php
• main.js (can be named whatever you would like)
• index.php
• page.php
• single.php

Once these files are created, we are finally ready to write some code!

style.css

This file may have been one of the most confusing to me when I first got started creating custom themes.

Usually, when you start a new web project in PHP, everything starts with the index.php file. Well, not with WordPress!

You won’t even be able to activate your theme without first setting up the style.css file.

At the very top of this file, you are going to need to create a comment section. This section will give WordPress all of the details it needs to know about your project such as the theme name, the developer that created the theme, what version of PHP is needed to run the theme, etc.

/*
Theme Name: ejwd_carls_computers
Theme URI: https://eranner.website
Author: Eric Ranner
Author URI: http://eranner.website
Description: A Custom Theme for Carl's Computers in Prompton, Pennsylvania.
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

Once you’ve saved the file, you’ll be able to see your theme in the Appearance part of the WordPress dashboard.

Now, you won’t be able to see much once you activate the theme… And that’s because we haven’t written any code yet!

Now it’s time to actually hook up our stylesheet and our JavaScript!

functions.php

Alrighty then! We’ve arrived to the most dynamic file in the custom theme directory, the functions.php file!

To be cheesy, this is where the magic happens! All of the functionality of your custom theme SHOULD flow through the functions.php file. This is where shortcodes are called into your theme as well as dynamic content like custom post types. This file needs an article or two all by itself but for now, we are going to use it to load our CSS and JavaScript.

To do this, we are going to use our first built-in WordPress functions, wp_enqueue_style(), wp_enqueue_script(), and add_action().

<?php

function set_up_ejwd_carls_computers_theme() {
wp_enqueue_style('style', get_stylesheet_uri()); //loads the style sheet style.css
wp_enqueue_script('carls_computers_main_js', get_theme_file_uri('/main.js'), array('jquery'), '1.0', true); /*loads the main.js file (or whatever you named it) also pulls in jquery just in case you need it*/                 
}

add_action('init', 'set_up_ejwd_carls_computers_theme'); //adds the theme files on initialization

To test everything, I will usually go back in to my style.css file and change the body background-color to red, save it, and then check and make sure when we visit the homepage it’s red.

I usually test the JavaScript file by simply throwing in alert(‘working’). Again, visit the homepage and you should receive the alert.

Now we’re rolling. Everything is in place to make our custom theme! Now we just need to figure out how WordPress determines what it wants to show on the screen.

index.php

It’s finally time to see a “hello world” in our browser!

But first, let’s take a second to understand what the index.php file actually is.

In a nutshell, WordPress looks for pages and posts based on naming convention. If it can’t find a page or a post that matches what it’s looking for, it eventually will land on the index.php file.

To simplify our demonstration, we’ll treat our index.php file as our homepage (although there is certainly a better approach in using the front-page.php file).

For now, lets just treat the index.php file as our home page and pull in some “boiler plate” code.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Carl's Computers</title>
</head>
<body>
    <p>Hello world</p>
</body>
</html>

Save this file and go to the root of your directory in your browser and there it is! Hello world!

Just like the first time you saw this when you made your very first website, the hard part is over! It’s all downhill from here!

Now, you may notice that you can’t access the WordPress toolbar and that’s because we need to call it in. This is easily done by adding the wp_head() and wp_footer() functions in their respective areas.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Carl's Computers</title>
    <?php wp_head();?>
</head>
<body>
    
    <?php wp_footer();?>
</body>
</html>

And there you have it, our WordPress toolbar is there and we can develop our home page!

But wait… Isn’t the whole point of WordPress to allow for dynamic content?

Right you are!

That is where the other required files come in!

page.php and single.php

These two files can easily get mixed up, especially when we cover the “WordPress Loop”, but to sum it all up a nice little package:

The page.php file is used to display pages and the single.php file is used to display posts.

Confused? I know I was when I first started WordPress development. I mean, really they are very similar.

To try and “clear the air”, a post is something like you’re currently reading. They are typically used for daily blogs or can even be manipulated to displaying products and eventually can be used to create shortcodes (advanced topics for another day).

Pages however refer to your main pages that you want on display always, such as your About Us and Contact Us sections of your website.

For our discussion today, all you really need to know is that they serve different purposes and will pull from their respective areas when you use the infamous “WordPress Loop”.

Displaying pages and posts – The WordPress Loop

Although WordPress is a fully loaded framework with many fantastic built-in functions, none are more important than the “WordPress Loop”.

This is at the core of making your website dynamic and it always amazes me that it is one simple while loop.

while(have_posts()){
   the_post();
   the_title();
   the_content();
}

That’s it! That’s all you need to display a post or page. You can see now why it’s a little confusing between pages and posts. They both use the same loop. WordPress however uses the naming convention of single.php or post.php to differentiate where it should pull data from the database.

Here is a quick breakdown of what the loop is doing:

• have_posts() – basically grabs all of the posts or pages. If it doesn’t find anything (like what would happen with a brand new project) it displays nothing.
• the_post() – this function sets the current post in the while loop so we can access the other functions on each individual page or post.
• the_title() – this takes the title that you entered in the title line of the page or post you created and displays it.
• the_content() – this function grabs all of the details from the “body” section of your page or post and displays it.

So lets put it all together:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Carl's Computers</title>
    <?php wp_head();?>
</head>
<body>
    <?php
        while(have_posts()){
            the_post();
            the_title();
            the_content();
        }
        ?>
        
    <?php wp_footer();?>
</body>
</html>

Now, this is going to look terrible but the good news is, our CSS and JavaScript files are already set up to remedy that!

And obviously you’re going to want to wrap the_title() and the_content() in some HTML elements and add some CSS classes like so:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Carl's Computers</title>
    <?php wp_head();?>
</head>
<body>
    <div class="ejwd-holding-container">
    <?php
        while(have_posts()){
            the_post();
            ?>
            <h2 class="ejwd-main-post-title"><?php the_title();?></h2>
            <div class="ejwd-main-post-content"><?php the_content();?></div>
        <?php
        }
        ?>
    </div>
    <?php wp_footer();?>
</body>
</html>

This is just the beginning!

You’ve done it! You’ve officially made your very first custom WordPress theme! This is just the tip of the iceberg and a very small showing of WordPress’s power and functionality. As you continue to experiment, you’ll develop a feel for how the whole ecosystem fits together and in no time – you will become a theme creation machine!