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…
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:
- Add a nav walker class
- Add the header markup
Add a nav walker class
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
Add the header markup
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:
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