Theme file structure best practice

Question

I'm building a custom theme and want to have an organized file structure. Is there a standard best practice? I looked at the file structure of popular starter themes and they all use different structures.

Some themes place important php files in the includes folder, others in a library folder, some in a functions folder... In some cases themes place their functions in the assets folder.

Below are the obvious folders which I respect:

assets

/css

/js

/images

page-templates

page template files go here

---

In which folders would it be considered best practice to add for example:

custom theme options, loops, footer, header, sidebar, custom shortcodes, helper functions, and other files that make a custom theme

Answer 1

You first need to ask yourself: Will this theme ever be maintained or used by other people than me? If so, read on, if not, you should only build code that will eventually make sense to you when getting back to this project after a few years.

If you are creating a theme that will be used by others, you should keep in mind that themes are supposed to be reusable in multiple use-cases. The WP way of doing that is through the use of child themes. All files in a theme will be loaded from the child theme, if they exist there, except for functions.php and style.css. So you should organize your file structure in a way that will allow people who use your theme to easily realize what files they need to copy and modify in the child theme in order to use your theme in ways you haven't thought possible.

You should also group functionality that people should not temper with in a few heavy files, prone to updating and advise your users not to override those and put the rest of the stuff in functionality oriented files that could easily be overriden in a child theme.

A typical scheme for a theme would be:

/assets
    /js
    /css
    /img
/includes => put your core functionality here, especially if you go OOP
/lang     => your i18n files go here
/modules  => if you create any

That's what I would use as a starter. When I write modules i think of advanced functionality that will only be used in some particular cases and is completely turned off in other cases. If you like things cleaner, you could move /modules in /includes.

If you are familiar with MCV frameworks, it is also a viable model for structuring a theme, even though it's not as easy to understand for the average user.

Answer 2

I am tempted to close this as "subject to opinion", but as a moderator my vote would be decisive so I am going to let the community decide that part. And I'll try to answer in a way that isn't subject to debate.

WordPress Core does not require any particular folder structure except that your theme be in wp-content/themes/{your_theme_name}. You can put all of your files in that folder if you want, and for a small theme you probably should.

As your theme gets larger, breaking things up into folders becomes necessary for organization. A folder of stylesheets, one for Javascript, and one for theme images is pretty reasonable, but the names don't matter at all, so long as you don't use ridiculous names. Any programmer worth being called that will be able to sort out that js, javascript, and scripts are probably the same kind of thing-- likewise with css and stylesheets, or styles. Don't worry too much about it.

If you have classes, I tend to group those into a folder, but, again, it isn't necessary.

I also group page templates (the bundled ones don't always do this and in some cases do it in what I consider peculiar ways).

That brings me to... get_template_part() and some related functions are capable of handling nested folders if you feed in the correct arguments, but in my opinion it becomes awkward with too much nesting so I would avoid more than a layer or two for files that are loaded by those functions.

Again, all of this is optional. The key consideration is the effectiveness of the organization. Does the structure make sense? Will someone look at this later and wonder what the $#%% you did? Will you look back in a year and wonder?