How to Build a WordPress Theme Part 1 – Theme Files

How to Build a WordPress Theme Part 1 – Theme Files

WordPress Theme Building Course!

This article is part of the How to Build a WordPress Theme course. If you’re new to WordPress theme building, be sure to start from the beginning of the course to get a complete picture.

full course
  1. How to Build a WordPress Theme – Preface
  2. How to Build a WordPress Theme Part 1 – Theme Files
  3. How to Build a WordPress Theme Part 2 – HTML, CSS, & PHP
  4. How to Build a WordPress Theme Part 3 – HTML Structure
  5. How to Build a WordPress Theme Part 4 – Conditional Tags
  6. How to Build a WordPress Theme Part 5 – Functionality
  7. How to Build a WordPress Theme Part 6 – Theme Design
  8. How to Build a WordPress Theme – Conclusion

Building a WordPress theme can be an intimidating process for beginners. There are files to deal with and things to consider that probably meant nothing before.

That’s okay, though. The majority of those files can be grouped together as concepts and those concepts come together to form a simple, functional WordPress theme.

underscoresIn this course, I’m going to teach you how to build a WordPress theme yourself using the Underscores (_s) Starter Theme by Automattic as an example.

Instead of building everything from scratch, I’m going to introduce you to the simple elements of a basic theme piece by piece. This makes things easier to understand because you can see the big picture as you learn.

Here are the two versions of the theme we are going to use as an example.

I will be using today’s version of Underscores. While there’s a chance your version of the theme will include minor changes from the one I use in my code examples, you should still have no issues following along.

Github VersionCustomizable Version

The Github version of this starter theme is ready for use immediately. The theme is already named and all function names used in the theme have a set prefix.

The customizable version allows you to set the theme name, slug (folder name, function name prefix, etc.), author information, and theme description before downloading the same exact version (without said changes) found on Github.

In other words, both sources will provide you with a working starter theme. The customizable version will allow you to brand certain elements of your theme in an automated fashion, saving you plenty of time.

Choose a version to download and let’s go over the theme files.

Underscores Starter Theme File Structure

underscores-files-rootHow you organize your theme files is something you will work on over time. With the exception of a file or two, your file configuration possibilities are limitless if you know a little PHP.

You’ll have to find a balance between your own organization methods, ease of use for your users (because they create child themes), and simple common sense.

For now, we’ll observe Underscores’ file structure and use it as a starting point, including its extra but unnecessary files.

Root Files

As you read through the article, open the files when we cover them. Look through the code.

Do not be intimidated by the number of files in the theme root. Many of them are self-explanatory based on the file names. Others can be grouped together because they behave similarly. Let’s observe those groupings.

The main HTML structure files handle the site header, footer, content column, and sidebar column.

The names given to these files are more about semantics than positioning. While the header is usually at the top of a website, the footer on the bottom, and the content and sidebar columns configured side-by-side, that is not a must. The natural HTML flow of these elements are stacked one on top of the other.

You’ll find this structural HTML in a series of files. The header.php, footer.php, and sidebar.php are exactly what you expect them to be. They build the site header, footer, and secondary container referred to as the sidebar.

layoutThe content container is where things get tricky. The WordPress Template Hierarchy takes over and the “content” portion of the HTML structure uses specific files based on what kind of WordPress page is being loaded.

The default file to fill this position is the index.php file. It includes the container that typically sits beside the sidebar and displays the page’s main content.

However, WordPress knows to use this file as a last resort. Instead, it looks for other files in your theme root by name and uses them if they have a specific purpose.

WordPress Posts

When a single WordPress Post is loaded, WordPress will look for the single.php file to serve as the content column. Because it exists, it will be used. Plain and simple.

However, this file only codes the content container shell. Nested within it is the WordPress loop. It’s inside of the loop that the actual HTML elements responsible for displaying the single post content is called, and that HTML is found in the content-single.php file.

Don’t let that setup confuse you. single.php and content-single.php basically behave as one file. You’ll learn how later in this course.

WordPress Pages

Moving on, when a WordPress Page is loaded, WordPress will look for the page.php file to serves as the content column. Because it exists in our theme, it will be used in the same fashion as above. Within that file’s loop, the content-page.php file is called to display the WordPress page content.

Archives, Search Results, and Error Pages

The same functionality applies to many other WordPress template files based on the template hierarchy. The main three files outside of your posts and pages will be archive.php, search.php, and 404.php.

Those files handle all archives pages (taxonomies [categories and tags], date archives, and author archives), search results, and error pages, respectively.

Default Template File

If none of the above files existed in your WordPress theme root or the page being loaded was not specific to any WordPress template, WordPress knows to look for the aforementioned index.php. It is your generic, fallback template.

Again, you’ll want to take a good look at the WordPress Template Hierarchy for a deeper understanding of the order of operations for these files. WordPress knows exactly what to look for based solely on file names.

While there are many instances where other files will still be served before the index file, for the sake of simplicity in our theme, it’s index’s time to shine.

Within the index.php there’s a loop just like the other template files. However, this loop goes on to call the content.php which serves as the generic content file. It’s very similar to the content files called by your single and page templates. However, it is designed to cover all bases no matter the type of page being loaded.

For most themes, the blog home (where the feed is displayed) depends on the index file. That’s the case with Underscores.

layout-pagesSo what happens if the blog has no published posts yet? Instead of the index file calling the content file, it will call the content-none.php file instead.

It’s very simple logic. All of the files mentioned above create the main site structure in WordPress.

The header, footer, and sidebar are considered to be static. The content changes based on the type of page being loaded. Simple stuff.

With the entire HTML structure of your theme in place, there are a few other files that either your template files or WordPress will call on. Let’s discuss those.

Comments Template Function

The comments.php is responsible for the display of your comments, pings, and comment form. Though you typically only see comments on WordPress posts, they are prepared to display on WordPress pages as well.

In both your single.php and page.php files, the comments_template() function is used to enable comment functionality. That WordPress function knows to search the theme root for your comments.php file. Again, simple stuff.


Functions File

Of course, WordPress wouldn’t be what it is without the awesome functionality that extends the software in whatever direction you desire. That’s where the functions.php file comes in.

WordPress knows to look for this file in the theme root. It is used primarily to set up theme functionality. While basic PHP can be used to extend this file’s reach to other PHP files, it is perfectly normal to build your theme details right here.

Things like registering widgetized areas, setting thumbnail sizes, and loading theme resources such as javascript files can all be done from this file. WordPress will automatically look for it so whatever you put in it will considered important.

Theme Stylesheet

style-css-comment-blockThe last (but not least) of the important files would be your stylesheet. The style.css is a WordPress theme’s main stylesheet. It must be included in a theme and it must be in the theme root. There are no exceptions.

Reason being, the very first thing that must be in this file is a comment block with important information about your theme. WordPress will look for this information and use it to output information about your theme in various places.

When you are in your WordPress dashboard and you navigate to the Themes page to see your installed themes, all information you see comes from that top comment block.

Another reason why this file is important is because your theme is nothing (to the average user) without CSS styles. This is where those style rules belong.

Another stylesheet included in Underscores that’s often overlooked is the rtl.css file. RTL means “right to left.” This file is used to adjust your theme styles for languages that read right to left. Usually, it doesn’t take much CSS to make this adjustment.

When you’re building your theme and testing it with the resources outline on the Tools page, you’ll get the opportunity to test your theme in right to left fashion. You’ll use this stylesheet to handle any necessary adjustments.


On the WordPress dashboard Themes page (and a few other random spots), you will also notice a screenshot image file.

Screen Shot 2014-01-22 at 5.13.37 PM

It can be branded for your theme or company. It can also be a simple screenshot of your theme. WordPress will look for a screenshot.png file. Be creative.

Root Directories

First of all, understand that WordPress does not require any directories in your WordPress theme. They are simply used for file organization and their names are 100% up to you.

That said, at the time of writing this article, Underscores comes with inc, js, languages, and layouts.

“inc” directory
This directory, short for “includes,” contains PHP files that are an extension of the functions file. As stated earlier, the functions.php file will be ran by WordPress no matter what. So “including” or “requiring” other files from the functions file will ensure their use as well. The Underscores functions file calls the files in this directory – /inc/custom-header.php, /inc/template-tags.php, /inc/extras.php, /inc/customizer.php, and /inc/jetpack.php.

Because these files are not required by WordPress nor are they part of the WordPress Template Hierarchy, we will not discuss them in detail. However, a description of each file’s purpose can be found in the top comment block of the files themselves.

“js” directory
This directory contains the theme’s custom javascript files. It includes the /js/customizer.js, /js/navigation.js, and /js/skip-link-focus-fix.js files. All Underscores code that requires a javascript file to be loaded (one that is not already included in WordPress) calls to the appropriate file in this directory.

“languages” directory
Depending on whether or not you are releasing your theme for distribution, you may need to prepare it for use in other languages besides English.The languages directory is a place to provide instructions and necessary files for translation. Again, this directory can be placed anywhere as long as the PHP looking for it knows where to find it.

“layouts” directory
This directory contains two simple stylesheets for the configuration of the aforementioned content and sidebar columns. Underscores knows that most blogs either have a content/sidebar configuration or sidebar/content. So these two files provide sample CSS to use in order to easily configure those columns. Personally, I like to delete this directory immediately as well as the /layouts/content-sidebar.css and /layouts/sidebar-content.css files in it. I’ll either write my own layout CSS or I’ll copy the CSS from these files and put it in my style.css file in the root.

Seeing the Big Picture

That’s a ton of information, right? Eh… not as much as it seems. The way it all comes together is fairly simple and once you understand how WordPress treats theme files, it becomes incredibly easy to understand any theme’s file setup.

If necessary, go back through this article one more time and make sure you’re opening files and skimming through them as I point them out. You will notice many similarities between multiple files and recognize basic HTML structures.

If you haven’t already, install Underscores as-is on your development WordPress install so you can see that it is a fully functioning, style-less theme.

Once you understand everything in this article, it’s time to break things down… the good stuff. Let’s go.

WordPress Theme Building Course!

This article is part of the How to Build a WordPress Theme course. If you’re new to WordPress theme building, be sure to start from the beginning of the course to get a complete picture.

full course
  1. How to Build a WordPress Theme – Preface
  2. How to Build a WordPress Theme Part 1 – Theme Files
  3. How to Build a WordPress Theme Part 2 – HTML, CSS, & PHP
  4. How to Build a WordPress Theme Part 3 – HTML Structure
  5. How to Build a WordPress Theme Part 4 – Conditional Tags
  6. How to Build a WordPress Theme Part 5 – Functionality
  7. How to Build a WordPress Theme Part 6 – Theme Design
  8. How to Build a WordPress Theme – Conclusion
  1. I’m still a noob in WordPress theme development, and this course is surely helping me a lot. Thank you so much! cheers.

  2. I was looking for somewhere to digging into WP and I found here.
    So there’s a lot to learn here.
    Thanks Sean for your efforts.

  3. Hi Davis,
    Thanks so much for this great effort! Really your clear to understand explanation of fundamental stuff surprise me!
    I’ve started my wordpress journey couples of weeks ago and it’s just now I found your course. Definitely I think your course MUST BE pointed on and codex as first reference tutorial before coming on those sites that on my view need some background. BRAVO

    • Wow! I really appreciate that, Ismael. Most of what I write comes from the fact that not too long ago, I was also on .org and a few other sites totally confused about how to get started. I wrote my tutorials to address the fact that they didn’t exist when I needed. THANK YOU for confirming that I was able to save you some trouble. That makes my day!

  4. Hi! I really appreciate your effort for putting this tutorial together. I think i might of found the direction to go after studying html and css. I watched a full teamtreehouse tutorial “Theme creation with _s” w/e. I am glad, that I torrented it though. The thing is the “teacher” was like copy and paste this is this and that is that, next copy and paste etc. All i learned from that course basically was, how to use CSS, nothing more nothing less (rhymemaster) …. Anyways, now that I read this article once I already feel smarter! I am gonna go though this article atleast one more time!


    • Thanks for the kind words! There are different teaching styles out there and I’ve found that different kinds work at different times based on where the “student” is in his or her learning. I wanted this course to be all about the concept as opposed to the code… that way everyone can still manage when thrown a curveball, you know? I’m happy to know it’s working. Thanks again for the feedback!

  5. Dear Sean,

    Thank you so much for this wonderful tutorial. I am so glad I found your website!
    Though, I am somewhat confused since I can’t find the files between content-none.php and content.php. I think underscores is updated and these files are left out now? There are also
    Can I do your course without these files? Could you explain me, why they are left out and how they are replaced?
    Thank you SO much for your effort!!

    • Hi Julia,

      Sorry for the delayed reply. It just looks like they’ve changed the theme structure a little bit. Those files are not inside of the folder called “template-parts” and continue to serve the same purpose.

      Also, please note that this course teaches you how to find your way around a theme. But every theme will be different. Likewise, a theme can change over time as you’ve noticed. So as far as if you can do the course without the files, there really isn’t much to “do” with the course. You should just read it all to get an understanding of what is what. Because as you start to look at other themes, the concept will be the same but several things will be different.

      I hope that makes sense!

  6. Thanks Sean, this step by step and why is that, is very clear to understand. I was looking for an easy to read guid about _s and theme coding.

  7. Hi Sean,

    I might be misunderstanding something. So I have underscores up and running – and your tutorials have totally helped. So I understand how to style everything – but should I be putting the actual content in the physical code – or should I be using the theme editor in wp-admin. like let’s say I want “img01.png” to be my background image – there is a place to put it in on my wordpress gui admin page – but should I? Or should I “hard code” it into my custom theme?

  8. I genuinely admire your effort for putting this educational together. I think i might of located the path to move after studying html and css. I watched a full teamtreehouse academic “subject matter advent with _s” w/e. i am glad, that I torrented it although. The aspect is the “instructor” became like copy and paste that is this and this is that, next copy and paste and so forth. All i found out from that path basically turned into, the way to use CSS, not anything more not anything much less (rhymemaster) …. in any case, now that I read this newsletter once I already sense smarter! i’m gonna go even though this text atleast one extra time!

  9. I can not thank you enough! I will DEFINITELY buy something for the store to show my appreciation! Thanks again!!

  10. Thanks for creating this tutorial. I just came across it at the right time. As I am new to wordpress development, I was finding it rather difficult to understand how WordPress processes themes. There is a bit to go I’m sure but you have got me on the right footing.Cheers

  11. Hi Sean, I just watched your 5 videos on youtube and just need to say thank you. I’m new and have been struggling to understand WordPress developing and building custom themes for awhile. You videos, which i’m going to watch again, have answered many questions already. I built my current WP site from a youtube channel, but I also have another I’m to fearful to touch that I paid a developer for! Im determined to be able to edit it for myself and one day for others. I have many of questions still but right now just thanks.

    • Sorry for the slow reply. Thanks so much for watching the series. I hope you’ve been able to understand things up to this point! Keep going. We all started from the same place. It gets wayyy easier over time. 🙂

Leave a Reply

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