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:

{type}-{name}.ext

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

Example Loops

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

JavaScript and Includes

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.

Keeping custom include and javascript files in a separate folder adhere’s to common coding standards and will help keep your include files secure and organized.

Conclusion

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.