One of the teams I work with has been using Sage for theme development in WordPress. The other developers are a bit ahead of me as they do more custom theme development than I do, so I’ve been playing catch up a bit.

Sage does some cool things, and I think that once I’m used to it it will save time. But I also think it’s overkill for some jobs, and it’s set up very much for basic blog or website theming, rather than more customised jobs, which might need some more wrangling to get it working nicely.

I’ve got going with it on two projects now. In both cases it’s been a bit painful and I don’t feel that the getting started process is well documented. So I’ve decided to document my process for getting a Sage-powered theme up and running using Bootstrap 3.

Sage claims it comes with Bootstrap, but they’re actually moving it towards a place where it’s de-coupled from its front-end framework. However, Sage ships with Bootstrap, but they’ve removed the nav walker and containing markup that makes a Bootstrap nav work.

Here we go…

Setup WordPress

You know what to do!

Clone Sage into a new theme directory

> git clone https://github.com/roots/sage.git theme-name

Commit a clean Git repository

My own, personal opinion, is that you should then commit a clean, history-free repo to git. So I delete the .git directory, create a clean repo and commit the files into it:

> cd theme-name
> rm -rf .git
> git init
> git add *
> git add .*
> git commit -m "New theme based on Sage starter theme"

Get Soil plugin, or remove support for it

If you want to use the Soil plugin then you’ll need to grab that to – you can clone it into your plugins folder. Soil seems to now be, in theory, paid for, I think, but it’s still on GitHub too:

> cd ../../plugins
> git clone https://github.com/roots/soil.git soil

If you’re not using Soil then it’s probably a good idea to remove the theme support for it from lib/setup.php and commit that. I’d review and/or remove the post-formats while you’re at it.

Get the Bootstrap nav back up and running

Once that’s done you’ll need to start getting the Bootstrap nav in. This needs you to do two things:

  1. Add a nav walker class
  2. Add the header markup

Add a nav walker class

The code for the nav walker class is here.

I create a new file to contain this class called lib/bootstrap-nav-walker.php and insert the code into that.

You’ll need to include this file in the $sage_includes array in functions.php too.

Add the header markup

The code for the header markup is here.

You’ll need put this code in your templates/header.php, replacing the code that is there.

You may want to add the navbar-right class to the included nav element to shove it to the right.

Install and compile

You’ll need Node.js and NPM installed. I won’t go into details on that here.

Once you’ve got them you’ll need to go to the theme’s directory and install the build tools and components using:

> npm install
> bower install

And once you’ve got the build tools, you should be OK to compile the assets:

> gulp

With all that done, you should have a clean, Bootstrap-ready theme ready to build on.

I’m sure some of this could be automated, or Sage forked to include it, but this is how I currently get started.

Check out Sage, including its documentation, at roots.io/sage