Organizing and Naming Your Themes' Template Files for Clarity and Convenience
Whether you’re creating a WordPress theme for sale, for a client, or for your own site, having a good naming structure and taxonomy for your theme files is important. It not only helps you keep your site files clean and organized for yourself, but provides a quick reference for other developers who may be viewing the files for the first time.
The Importance of Structure
File names are important to WordPress. Anyone who has developed for a WordPress theme is intimately knowledgeable about style.css, single.php, and functions.php.
How you name your own custom theme files can be just as important.
As professional developers and designers, we all know the importance of clean, well structured code. The same should be said about your site files.
- Avoiding conflicts. Having a good structure for your own custom theme files that avoids required WordPress files can help prevent problems and conflicts while you’re developing a theme.
- Easy reference. If you’re working with a complex theme with dozens, if not hundreds of theme files, searching for randomly named files can be a nightmare not only for yourself, but for others who might not be familiar with “your system”.
- Extendability. Custom files and includes can be used in child themes. These follow the same parent - child relationships as standard WordPress theme files. Keeping a common structure that flows from parent to child themes will help speed up development in the long run.
- It’s just good practice. As professional developers and designers, we all know the importance of clean, well structured code. The same should be said about your site files. It speeds up the development time, cuts down on customer service / troubleshooting issues, and frankly, it just looks pretty.
Terms of NO Use
Before we get into possible naming structures for our custom files, we should talk about the file names we should NOT use. These are files the WordPress Core requires to display a theme properly.
The list below comprises the files that are reserved for WordPress and should not be used. This is pulled from the WordPress Codex and will probably change as WordPress matures. But, this will provide you with a start.
style.css rtl.css index.php comments.php front-page.php home.php single.php single-<post-type>.php page.php category.php tag.php taxonomy.php author.php date.php archive.php search.php attachment.php image.php 404.php
Adopting the Existing Foundation
The key to a good file structure is using a simple, yet extendable file naming scheme. Luckily, WordPress has already brought us 90% of the way with their existing structure. All we need to do is carry this over to the structure of our files.
Here’s the base that WordPress has already presented:
Look familiar? It should... it’s format is used for targeting theme template files to single, page, taxonomy, and other theme files. For example: page-about.php, single-348.php, or taxonomy-untitled.php
Using this same base for our custom theme files keeps them simple to understand because they follow an existing structure.
Below are a few examples of different types of files we might be able to use this format in to name our files.
Example CSS Files
Using multiple CSS files in your theme can help clarify the coding as well as improve load times by conditionally serving css files only when they’re needed.
To keep your CSS files organized in your file structure, you can append the file names with a name to identify where they belong.
Note: These are only example file names, you still need to include these files in your pages for them to work.
style.css style-templates.css style-ie.css style-ie6.css
Example Custom Templates
Custom page templates are a very powerful part of the system. If you use a lot of custom templates in your theme, it’s good to have them all in one location and with descriptive file names.
In this example, we’ll use “template” as the prefix of your template file names to organize them:
template-nosidebar.php template-mycustomtemplate.php template-anothertemplatefile.php
Using some examples of the WordPress twentyten and twentyeleven themes, we can separate the loop code of files and and include them where they’re needed:
loop-homepage.php loop-search.php loop-taxonomy.php
Example Content Files
Again, using twentyeleven as an example, WordPress has separated the content sections of page codes as includes using get_template_part();.
Here’s a few examples of content file names:
content-page.php content-single.php content-custompage.php
For anyone working in developments after a while, this is a no-brainer, but an important one to keep mindful of when developing a theme.
These are just a few examples of a proposed structure for theme files and by no means the ONLY way of organizing your files.
If you have a structure you use for your theme files, list them in the comments below... I’d love to see how others handle this issue.