Organizing files and functions in a WordPress theme – my current state

Good organizing files and functions in a WordPress theme (respectively every coding project, of course) helps to keep it clear. This post shows my current state on organizing the files and functions in a WordPress theme.

The following structure is from my Photographus theme. I do not list all files and folders (you can find everything in the GitHub repo), the following is missing:

• the single SCSS files which get imported.
• files and folders from build scripts and other dev tools.

Here comes the file and folder structure of the theme (format adopted by the Jekyll documentation):

.
├── assets/ # all JS, CSS, images
|   ├── css/
|      └── scss/
|         ├── abstracts/
|         ├── base/
|         ├── components/
|         ├── conditionals/
|         ├── layout/
|         ├── templates/
|         ├── editor-style.scss
|         └── photographus.scss
|   ├── images/
|      └── starter-content/
|         └── featured-image-about-page.jpg
|   └── js/
|      ├── customize-controls.js
|      ├── customize-preview.js
|      ├── functions.js
|      └── masonry.js
├── inc/ # files with functions
|   ├── customizer/
|      ├── callbacks.php
|      ├── register.php
|      └── scripts-and-styles.php
|   ├── actions.php
|   ├── cache-functions.php
|   ├── filter-functions.php
|   ├── filters.php
|   ├── front-page-panel-functions.php
|   ├── template-functions.php
|   ├── template-tags.php
|   └── theme-updates.php
├── languages/ # language files folder (if not on W.org)
├── partials # template parts
|   ├── attachment/
|      └── content-image.php
|   ├── footer/
|      ├── nav.php
|      ├── theme-author.php
|      └── widget-area.php
|   ├── front-page/
|      ├── content-latest-posts-panel-short-version.php
|      ├── content-latest-posts-panel.php
|      ├── content-post-and-page-panel.php
|      └── content-post-grid-panel.php
|   ├── header/
|      ├── branding.php
|      └── nav.php
|   └── post/
|      ├── content-none.php
|      ├── content-single.php
|      └── content.php
├── templates/ # page templates
|   ├── large-featured-image-no-sidebar.php
|   ├── large-featured-image.php
|   ├── large-portrait-featured-image-no-sidebar.php
|   ├── large-portrait-featured-image.php
|   └── no-sidebar.php
├── archive.php
├── comments.php
├── footer.php
├── front-page.php
├── functions.php
├── header.php
├── image.php
├── index.php
├── page.php
├── readme.md
├── screenshot.png
├── search.php
├── sidebar.php
├── single.php
└── style.css
Code language: PHP (php)

Structure explanation

The highest level only contains files which cannot be moved into sub folders.

The assets directory

The assets folder holds the SCSS, JavaScript, and image files. The scss folder contains more folders with SCSS files, which are imported into theeditor-style.scss and photographus.scss:

• abstracts/ holds files with variables, mixins, and functions.
• base/ keeps the files which style the base HTML elements.
• components/ is the place for the files which style components (like a post, a comment or a grid item).
• conditionals/ is for browser specific styles.
• layout/ for layout styles (grids, header, footer et cetera).
• templates/ keeps files with template-specific styles (front page template styles, no-sidebar styles…).

I was inspired by several approaches for the SCSS organization – spontaneous I can name Atomic Design and RSCSS.

The inc directory

The inc folder is the place for all PHP functions of the theme. The functions.php just includes all these files. The functions are – if possible and sensible – grouped into various files.

• actions.php – all add_action() calls.
• cache-functions.php – all functions which work with transients.
• filter-functions.php – functions which are called by add_filter().
• filters.php – the add_filter() calls.
• front-page-panel-functions.php – all functions which have to do with the front page panels feature.
• template-functions.php – all functions which are not directly called from template files but cannot be grouped into other files.
• template-tags.php – functions which are called from template files.
• theme-updates.php – functions to provide automatic theme updates.

Because I grouped the customizer functionality into three files, I gave them an own sub folder customizer.

• callbacks.php – all customizer callback functions.
• register.php – function for creating settings, controls, and sections.
• scripts-and-styles.php – function to enqueue scripts and styles into the customizer.

The partials directory

The partials folder contains the files, which display parts of the theme and are included in other files. For example, the header/branding.php displays the website’s title and description, the post/content* files show the post content.

The templates directory

The templates folder contains the post type template files.

And that is my current state, which is of course exactly that: my current state and likely not the most elegant and best solution. You have comments, questions and/or suggestions to improve the structure? Write a comment 🙂