winterwoods

Well, I did run, and I got this picture as I promised. It was a lovely winter’s day with the sun bright and brittle and low. Because of its angle, the light shone in under the canopy, making the woodland stretched and luminous. Out in the open, frost clung on stubborn in the shade. I snapped the couple in the picture to make up the ‘two’ for today’s window – though, yes, they could also be ‘eleven’. Trust me, though, they are ‘two’.

For today’s window, I’m going to organise my directories. This is one of those deceptive choices that seems trivial at first blush, but can bite you hard later on if you don’t think it through. Much of the thinking here relates to which files and directories should be committed to version control and which should be grabbed from some other place. Where should your non-Web files be managed? What is the distinction between WordPress and non-WordPress content?

So today, I’m going to see if I can navigate some of those questions.

Firstly, I’m going to include non-Web space in the repo. I’ll want to commit all sorts of scripts and files that should not be available through the browser. If my repo starts with web space (that is, with a directory that contains my index.php) then I have nowhere to put useful non-Web files and directories. Like what? I may want to commit sample Apache configuration files, Vagrant files, scripts for managing the database, composer files – none of these should be Web-facing. Without a layer of non-Web space I’ll be forced to fiddle around with .htaccess directives to protect directories.

As you probably know, out of the box, you’ll likely find some key WordPress files and directories in this structure.

/
/index.php
/wp-config.php
/wp-content
/wp-content/plugins
/wp-content/themes
/wp-content/uploads

The trouble is, there’s a bit of a hotchpotch here of files we want to edit ourselves and those that belong to WordPress as a package. If you’re used to using a dependency manager like Composer, you’ll likely want to keep third party library code (such as WordPress itself) out of your version control system so that it can be easily updated and only commit the code you’re tweaking. In practical terms, that will mean local themes and plugins and a few other bits and pieces.

So that’s the next principle I’m going to follow: separate content from core. In order to make this work, I will pull the whole wp-content directory from the WordPress distribution.

Finally, I intend to separate WordPress and non-WordPress files. In practice, that means placing WordPress code in a sub-directory beneath your site’s entry point. This provides a non-WordPress space in which index.php will live and, more importantly, any other static files and directories you might want to manage.

So, to reiterate, here are my principles:

  1. Include non-Web space in the repo
  2. Separate content from core
  3. Separate WordPress and non-WordPress files

So, what will my directory structure look like once I’ve finished with that? Something like this.

/
/non-web-stuff.sh
/site
/site/index.php
/site/wp-content
/site/wp

There are now three levels to this. I start with non-Web space for all my scripting needs and configuration pleasure. Web space begins at /site. This is the top level as far as the Web server is concerned. There, I can place any non-WordPress files and directories I want. I have also pulled wp-content out from the main WordPress directory and I will check it in to version control at this level, because it will likely contain child theme and custom plugin work. /site/wp will contain the core WordPress codebase. This will be installed from third party sources and will not be checked in to version control. So, when I blow /site/wp away and start again with an upgraded version, my /site/wp-content directory will remain safely separate.

Well, that’s quite a nice looking structure. How on earth am I going to get WordPress to co-operate with it in a way that won’t involve too much work for every installation? Tomorrow, I’ll investigate the increasingly friendly relationship between WordPress and Composer.