Project/repository structure

[0xZakk]

Need to come up with a draft file tree structure for WP projects

[0xZakk]

File structure

I want to outline a proposed file structure for a starter WordPress theme that we can use for our WordPress projects going forward. The architecture I have in mind is heavily based on underscores, with the following goals:

1. To keep the root directory of the theme as clean as possible, so as to make the theme approachable.
2. To have as many aspects of development implemented in an easy-to-follow convention
3. To have a much work automatic or abstracted as possible.

You could say, if underscores is the first 1,000 hours then the goal of this theme is to be the next 1,000.

Root directory

The root directory will be as simple as possible and follow this basic tree structure:

base-theme/
├── 404.php
├── archive.php
├── dist
│   ├── favicons
│   ├── icons
│   ├── images
│   └── js
├── footer.php
├── functions.php
├── gulp
│   ├── index.js
│   └── tasks
├── gulpfile.babel.js
├── header.php
├── index.php
├── node_modules
├── package.json
├── page.php
├── readme.md
├── screenshot.png
├── search.php
├── single.php
├── src
│   ├── images
│   ├── js
│   └── sass
├── style.css
├── style.css.map
└── template-parts
    ├── page-about-us.php
    ├── page-home.php
    ├── page-none.php
    ├── page-search.php
    ├── page.php
    ├── single-job.php
    ├── single-product.php
    └── single.php

The intended goal of the root directory is to have as few loose files as possible. This makes the theme more approachable.

Template files

One of the most common causes of complex and unapproachable themes is the template files. Often because every page in the site will get its own page-*.php or single-*.php at the root level of the site. If the site is even relatively complex or has a lot of pages, then your root directory is cluttered with a lot of pages. Additionally, each page-*.php or single-*.php file contains the markup for the entire page, which is often repetitive between templates. Underscores solves this second problem by using a template-parts/ directory. I'd like to take that one step further and use it to solve the first problem as well.

Under this theme structure, rather than have a single page-*.php template for each unique page on the site, we would have a single page.php at the root level of the directory. This template is almost 1:1 with the page.php in Underscores but with one important difference: rather than pass the content type to get_template_part() inside the loop, we pass the page name:

Underscores:

<?php
  while ( have_posts() ) : the_post();

        get_template_part( 'template-parts/content', 'page' );

    endwhile; // End of the loop.
?>   

Proposed:

<?php
  while ( have_posts() ) : the_post();

        get_template_part( 'template-parts/content', $post->post_name );

    endwhile; // End of the loop.
?>   

Then in the template-parts/ directory, we would build out a template file for each page name, i.e. template-parts/content-about-us.php.

We can follow the same convention for single-*.php and archive-*.php.

Gulp

This base theme leverages the gulp architecture I've proposed before. The gulpfile.js is at the root level of the theme, it requires an index.js file in a gulp/ directory that in turns cycles through all the gulp task files inside of a tasks/ subdirectory. This makes every gulp task act like a 'plugin' that can be easily changed or replaced. Some of the key tasks I've modified are:

CSS: The CSS task used to spit out styles.css and style.map.css files into the dist/ folder with the other tasks. For Rhombus, I modified it to instead write these to the root level of the theme as the required style.css file. The header for the style.css file is built in the gulp task using data from the package.json file.

The main role of the CSS task is to build scss into css. I wont propose an architecture for our scss here, though there are some things from Rhombus that went really well. The only thing I will propose is moving the scss files into a sass/ subdirectory of the src/ folder, rather than have it at the root level of the theme, like in Underscores.

JS: JavaScript should also be kept in the src/ folder and built into dist/js/. I also don't want to propose a solution for how we handle our JS here, as that should also be a separate conversation, but there are some things we can pull from Rhombus.

src/ and dist/

All 'assets' or things that need some level of processing with Gulp - even if it's minor - should start in the src/ directory and be built into the dist/ directory. In the above file tree, I've proposed that scss, js and images start in the src/ directory.