Organizing theme files

Part 6, how to organize theme files to maintain them easily

Buy the book

These articles are excerpts from the book's manuscript draft. You can read the book here or in an easier-to-read format and finalized by purchasing the finished book.

Table of Contents

A simple theme, plugin, or any project can store all code in one folder or file. But I can not recommend working like that. It is better to organize the files and the code to be easy to find and maintain in the future. So I recommend using smaller files as templates and logic that can be used and maintained separately.

This tutorial explains a suitable file, code, and folder structure for a WordPress theme.

The starting point

At this point of the development process, we have all the code in single index.php, functions.php, and styles.css files. This kind of code structure might be ok if the development would end here, but it does not. In fact, we are only in the beginning.

We will create different page templates for single pages, front-page, 404-page, search results, articles, and so on. These files will have parts that are common to all of them but differ in other parts. So how are we going to tackle that kind of problem? First, we need to divide the code into reusable blocks and create page templates that can be easily maintained. Next, we will create the folders and files needed.

The idea of code blocks

As a simple example, think about the page header and footer. They will repeat the same on all pages even though the page content will differ. The same header and footer will be on the front page, and the same header and footer will be in every single post (article). We should never repeat the code multiple times because of potential risks and confusion when changing the code later. If you have the same code in multiple files, you will inevitably forget to update it in one and so break the theme or design.

The solution

The solution is to put the header in one file, the footer in one file and the page contents in another. WordPress is designed this way. But here I am, taking this further as every theme should. We are creating multiple files, and we are breaking even the functions.php file into multiple blocks that we only load in one main functions.php file.

Remember – the index.php version we built so far was only a demo to show how the theme works; some of the code is in the theme file, and the content is stored and fetched from the database. So, before I go into the page contents, I show you a model of folder structure, and we will split the functions.php into smaller maintainable pieces.

Theme files and folder structure

Below is an image of an example folder structure; we will build and use the same structure for this theme.

Theme folders.

As you may notice, I have named the folders so that the names begin with an underscore. The underscore is there because code editors list the folders first on top of the file list. This naming convention is my personal preference but a good one.

_css folder

The folder name is self-explanatory. All CSS files are stored in this folder. So, what about the style.css file in the theme root folder. That file is mandatory, but we do not need to include our styles in that file. We will enqueue style-files using functions.php anyway. So it pays to locate the files in a meaningful location.

_inc folder

The folder _inc will include the functionality of our theme in easy to maintain files. We will split the functions.php file into smaller files which each have their specific purpose. And as small files, they are easy to load, maintain and debug.

_js folder

The _js folder is for JavaScript files we may need in the future. We do not have any, but if the need arises, we’ll have the folder ready.


The _themeparts folder is in the central role of creating our pages. We will again split the pages into smaller pieces – “parts” that we reuse on multiple pages. This method allows us to use a separate header, footer, or any other part for any specific page or post. So, you can make a different header for most of the pages and a different header, for example, on a campaign page. It is also easier to understand how the pages are built up and maintain the code.

Themeparts idea.

Functions.php structure

I do not add all the code in the functions.php file but separate files responsible for only one task. I then call these files from the functions.php file located in the theme root folder. The whole idea is to have small code units to maintain, and as such, it is also easier to control the logic of the functions file.

We want to load the CSS files, Google web fonts, and some scripts. Loading external files is usually done in the functions.php in a WordPress action wp_enqueue_scripts Instead of adding the function in the functions.php, I created a file, load_files.php This new file will contain the function for the WordPress action. Because the code is in a subfolder and an arbitrarily named file, WordPress has no idea how and when to load the file and run the code. We will instruct the main functions.php file to load the external file using a require_once expression.

Loading external functions in separate files.

From now on, I will organize the theme code like this. It will make it easier for you to follow the code and easier to alter and maintain the code.

Next steps

Next we will take care of our code and store it in a safe location – GitHub. We will also learn to use git version control.

Picture of Kari Selovuo

Kari Selovuo

Leave a Reply

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