Hopefully someone finds this helpful as I’ve had to figure out some of this as I go or just from trial and error. There aren’t a lot of resources for building themes that really spell things out, so it’s good to look at what others are doing.
This post is more basic directory structure and not much code beyond organizing theme specific functions.
Core Thoughts
The whole point is to reduce bloat while increasing utility. Make it easy to develop in for yourself and for any future development to happen even if its not by you. Basically… K.I.S.S.
Directory Structure
First I’m going to overview my directory structure of a basic theme.
Basic Theme Structure
- theme-folder
- css
- js
- imgs
- inc
- index.php
- functions.php
- style.css
You can definitely get further organized with this by putting your js, css, and images in an /assets/ folder. You can even drill deeper with specific folders for files like page templates and template parts.
Not all sites need that much organization, but if you’re building something with a lot of layouts that are wildly different you may want to organize better.
Including Functions
Used to I would dump everything in functions.php until I graduated to including them in an array, which was only slightly more helpful in terms of it was neater looking and easier to navigate. That looked something like this:
https://gist.github.com/bmoredrew/8278090
But that’s not optimal because you have to manage each file. This is all preference but what I do now is include everything from the /inc/ or /lib/ (or whatever you want to call it) folder. So my functions.php is just a few lines and grabs my entire folder:
https://gist.github.com/theandystratton/5924570
(stolen from @theandystratton)
Template Structure
I’ve noticed with a lot of “off the shelf” themes each template will have a name (and therefor appear as a selectable layout), and maybe that’s for flexibility purposes, but I prefer to only have a few where needed.
Usually Full Width and any Landing pages will get a template name, otherwise I want them to auto assign appropriately. One way you can do this is by understanding proper hierarchy.
The Template Hierarchy
Generally a pretty basic site only has a few templates to consider:
- Front Page
- Interior Page
- Full Width Page
- Blog Page
- Single Blog Page
Which you should be referring to the Template Hierarchy Map. It will probably end up looking something like this:
Index.php As a Workhorse
If you look at the template hierarchy map again you’ll see everything eventually waterfalls to Index.php
It makes sense to take advantage of index for templates that are sharing a layout. I’ll have designers that want to change things on 404 pages, search results pages, etc. Generally these end up being full width pages so I can re-use my full-width layout in my index for multiple pages.
Take-away Points
- Don’t over organize unless you have to
- Adhere to your own standards for coding and structure
- Easy on the template names in files, let the template hierarchy work for you
- Find ways to keep things lean by having utility files
Hi Drew
if including add on functionality in a theme, for example a jquery slideshow (which is kinda like a plugin having it’s own structure, js, css etc)
it would make sense to keep all these together in a folder called “slideshow” for example, as apposed to breaking it all up, this way I could add or remove the whole folder as required.
should this extra functionality go in a “modules” folder or something, not sure on the correct term to call it?
when building client sites I might have a lot of add on functionality, and it all gets a bit untidy and unorganized
hoping you can make some suggestions.
thanks
Hey Jamie,
This post is pretty old, and while still relevant you may want to look at the WordPress starter theme I’ve released to give you an idea how to structure things.
To answer your question though, I would still put the css, js, etc in an assets or specific css/js folders. The actual php/code to run those items I would put in a parts folder if being re-used and has its own set of HTML. If its just an actual function or similar being created, drop a new file in /lib/ so it can get automatically enqueued and the function will be available for you to use. If its just one place that has the slideshow I would just put it direclty in the template (front-page.php for example).
So you’d end up with a possible structure like:
/assets/css/slider.css
/assets/js/slider.js
Could go one step further and if its a js plugin:
/assets/css/vendor/slider.css
/assets/js/vendor/slider.js
The actual code:
/parts/slider.php
/parts/call-to-action.php
etc
Then in your template:
get_template_part('parts/slider')That make sense?