WordPress: Modular parent theme as git submodule to increase efficiency

Since branching out from in-house development on a huge CakePHP 2.x system back into an agency environment (and a very long time without blogging anything), I have been exposed to a lot more frameworks and technologies than previously which is great. One of which that I can’t say I had missed but definitely has a place in the dev world is Wordpress.

If you do any agency work or work freelance, you’re likely going to use WordPress for a lot of your clients which means setting up new environments quite frequently. You maybe have a base theme you copy and paste into each new installation to gain shared functionality, I just want to share something I do to make all the projects easy to set up and easy to update.

1. Super Theme

I will name the shared theme ‘super-theme’, this will hold all of the shared functionality and assets and act as a parent theme. For this, set up a new theme with the bare minimum and add any tools or assets you frequently use, I personally use gulp and roots in my themes. Here is an example of how my theme looks once ready

Screen Shot 2016-08-24 at 13.28.17


What’s important in this is mainly the assets directory, lib (Sage Roots) directory and functions.php file. Taking a closer look at these directories, you can see the styles are individual partials named based on what they contain (with no main scss as we don’t run gulp in this theme).

Screen Shot 2016-08-24 at 13.30.14

These scss files contain very handy classes and mixins I would want available across all of my sites, to give you an example, here is the contents of the padding file.

As you can see the padding styles are very handy for changing padding on elements without having to write any css over and over again as well as keeping sizing consistent.

2. Setting Up The Child Theme

Now that we have our super theme, you can create your actual theme that you will use however you normally do. In the child theme’s style.css, you must make sure to reference the super theme as a parent like such.

Once you have that in your style.css the theme will inherit everything from the parent theme, things like templates and such will be overridden if you create the same file in the child theme.  If you use sass and have assets in your super theme, you can add this to your main.scss (I would have an _import.scss file, which brings all the super theme assets together, so you only need to reference this one file in your child theme).

@import "../../../super-theme/assets/styles/_import"; // Imports all the SCSS

If done correctly, your new theme has access to all the styles, functions and base default templates from your super theme.

3. Tying it all together

I’m going to use git in this example, with this super theme you would probably copy and paste it into each new project and well that can get quite messy and unorganised. It also means it will be included in your git repository and be hard to track changes between different projects.

The best way to handle this is to create a new repository for your super theme (outside of any project), this will track all changes to the super theme alone. Once you have set up your repository, we will include it into your projects as a submodule – essentially a git repository within a git repository (but separated). Using terminal, go to the /wp-content/themes/ directory and use the following command

git submodule add https://<username>@bitbucket.org/<username>/<super-theme>.git

Replace the HTTPS url with whatever you use be it bitbucket, github or another.

Now when you are in the super theme directory, you can commit and pull / push to the super theme repository and when you are outside the super theme directory you will be dealing with your actual project ignoring the super theme. This is a great way to ensure that you can share functionality across all your WordPress projects, you can even create branches for specific projects if need be to keep things very easily manageable.

Leave a Reply

Your email address will not be published. Required fields are marked *