Table Of ContentSummary
Introduction
1
What is Sage?
2
Why Sage?
3
Starting a project
4
Installing the Sage starter theme
4.1
Theme setup
4.2
Planning out the theme
4.3
Customizing templates
5
Blade templates
5.1
Template files
5.2
Building template partials
5.3
Responsive images & post thumbnails
5.4
Displaying the sidebar
5.5
Customizing the front-end
6
CSS setup and organization
6.1
Default CSS and JS
6.2
Bootstrap
6.3
Browsersync
6.4
JavaScript and DOM-based routing
6.5
3rd party packages
6.6
Asset paths in CSS and templates
6.7
Theme functionality
7
Adding additional files
7.1
Namespaces
7.2
Take advantage of newer PHP features
7.3
Theme customizations
8
WordPress Customizer
8.1
Advanced Custom Fields
8.2
Theme deployment
9
Theme troubleshooting
10
Theme updates and maintenance
11
Resources
12
Wrapping up
13
CHANGELOG
14
Introduction
Theme Development with Sage
Thank you for purchasing a copy of the book. New versions to this book are released as the Sage starter theme goes
through major changes. You'll receive lifetime updates and will be notified via email when a new version is released.
Please write to ben@roots.io with any corrections or feedback!
Licensing and cost
Unlike the Sage starter theme, this book is not open source. I reserve all commercial and moral rights to the book and
supplied code (where not under an existing license).
Please buy a copy if you’ve received this book without paying.
About the author
Howdy! I'm Ben Word, a web developer & interaction designer who has been creating websites for over 15 years. My goal
with our open source projects at Roots is to help developers create awesome websites, and I've always been passionate
about web standards and tools that make our jobs more efficient.
My first encounter with WordPress was in 2004, and since 2006 I've been using it at my day jobs. I've had the opportunity
to work on a WordPress multisite network that receives millions of views per day for the blogs and newspapers part of the
Hearst conglomerate, along with running the marketing site for ShoreTel Sky.
Originally from Texas, I now live in the west side of Colorado Springs with my two dogs. I love traveling, overlanding, and
climbing. I'm new to yoga and slacklining, and hopefully soon mountain biking.
Thank you
I'd like to acknowledge and thank:
Everyone who has contributed to Roots by helping others on the forum, spreading the word, committing code,
opening issues, purchasing our educational materials and plugins, and more. Thank you so much for your support.
Craig, who helped evolve Sage into the next version by reworking almost the entire theme. The build process, the
file restructuring, the conversion to ES6, and more, are thanks to the work that Craig has done.
Scott Walkinshaw, my good friend, for all of the time he's put into Roots and our projects, despite how he never
uses WordPress outside of Roots and is naturally a Ruby programmer.
Phil Nelson, for the countless contributions to Trellis, and his tremendous level of detail with support on
Discourse, GitHub, and all of his work in general. He inspires me with his patience and kindness.
Kalen Johnson, for providing countless hours of support and contributions to Roots projects, especially the Blade
implementation in Sage 9. Still looking forward to trying one of his beers.
4
Introduction
Tools used to make the book
This book was created with GitBook. The source files are in Markdown which allows for painless code example blocks, as
well as letting me write with a syntax that I'm familiar with.
GitBook with a custom theme
Pages edited as Markdown in Atom
Git is used for version control
Sass is used for styling
There are some GitBook bugs that affect the various formats of this book that I'm working on trying to improve.
Who this book is for
This book is not an introduction to WordPress, or themes, and expects that you’ve done theme development before.
Things you should understand:
Keeping projects under version control with Git
Command line basics
HTML5, CSS preprocessors, basic JavaScript (with ES6), basic modern PHP
WordPress template hierarchy
Loops and WP_Query
Conditional tags
Template parts (get_template_part)
Enqueuing scripts and stylesheets
5
What is Sage?
What is Sage?
Sage is a WordPress starter theme. Sage was first called Roots and initially released in early 2011.
I created Roots when I was working at an agency in Northern Colorado in 2010 and had to pump out several new themes
every day. I had experience with WordPress themes before that job, but I had never been in a position where I was
regularly creating new themes. Previously I had been a Thesis user, but discovered that I wasn't a fan of using child themes
and hooks to make changes. I quickly realized that having a bare bones theme that's ready to start customizing was the
way to go.
The Roots theme started out by combining Starkers with HTML5 Boilerplate and Blueprint CSS. Starkers was one of the
first 'naked' WordPress themes and was created by Elliot Jay Stocks almost 10 years ago. HTML5 Boilerplate, the most
popular front-end template, was used in Roots back when it existed as Paul Irish's frontend-pro-template. Blueprint CSS
and 960.gs were the most popular front-end frameworks at the time, and Blueprint was my preferred choice since it had a
better starting point to work from.
On March 28th, 2011, Roots went public. Smashing Magazine tweeting about Roots, then mentioning it in their newsletter
and a blog post was directly responsible for a lot of the initial success.
Over the lifetime of the project the theme has undergone lots of changes, improvements, and re-considerations of best-
practices as the team has learned new things while the web moves forward.
Going back and looking at the first several major versions of the theme makes me feel embarrassed of a lot of my early
decisions, including moving the uploads folder to /media/ and rewriting all theme assets to the web root. Roots was far
from perfect, and to this day we still strive to improve it whenever possible.
6
What is Sage?
Some of the bigger milestones include:
Roots 3.0.0 (March 2011): First public release
Roots 5.0.0 (February 2012): Removed all frameworks except Bootstrap
Roots 6.0.0 (September 2012): Added theme wrapper
Roots 6.5.0 (August 2013): Introduced a Grunt based front-end workflow
Roots 7.0.0 (July 2014): Updated Grunt workflow, moved plugin functionality into Soil
Sage 8.0.0 (February 2015): Renamed theme to Sage, switched from Grunt to gulp
Sage 9.0.0 (February 2018): Replaced gulp with Webpack, new templates folder organization, Blade as a
templating engine, options to use certain CSS frameworks or none
Sage is not a theme framework, it is a starter theme. You should rarely need to update it, and typically you shouldn’t
create child themes from it. Being a starter theme, Sage is meant to be used as a starting point on a new project.
Sage can be implemented on any sort of WordPress installation, independent of our other primary projects (Trellis
& Bedrock).
Sage combines:
Dependency management with Composer and npm
Asset management and optimization with Webpack
Template inheritance with Laravel's Blade
Modern PHP & PSR-2 coding standards
An improved project structure
The first episode of Roots Radio, Ep 00 — Overview, gives an overview of some of the team members involvement in
Roots and an overview of the different Roots projects.
In Roots Radio Ep 05 — Sage, Chris Carr, myself, Nick Fox, and Kalen Johnson dig into a bit of the Sage philosophy, what
we are doing right now with Sage, and our own theming processes.
7
What is Sage?
What Sage has become
Sage has evolved into a full breadth starting point for website development and spawned additional projects to support
and enhance it. It has created an entire community of conversation on what web development should be and how it has
sometimes lost its way. It has grown into a team of open source developers who are dedicated to making the web better.
Roots embraces the open source ethos and believes in peer production. Through our team and community, we have
dedicated thousands of person-hours to building and continuously improving our projects since 2011. Over 300
contributors have come together to help make better tools for WordPress under the Roots name.
Who's working on Sage
We're still working on and using Sage because we're invested in improving WordPress and the web in general. Many
people use WordPress, and we believe there is a way to use it more efficiently.
A quote from The Changelog podcast on Modern WordPress with myself and Scott Walkinshaw, which was originally said
by Craig:
I think we’re all on the same page when it comes to WordPress. WordPress is a lemon, but the industry likes
WordPress, so let’s make lemonade.
Craig (@QWp6t) and myself are the project leads for Sage.
Craig joined the Roots team before version 7 in mid 2014. His knowledge in PHP and JavaScript has been an enormous
help in making Sage the theme that it is today.
8
Why Sage?
Why Sage?
There's been countless hours of research, development, and support put into Sage by the Roots team and community
since 2011. We strive to always use and improve best-practices in the theme, and we're consistent at keeping the theme
up to date.
Rather than coding an entire theme from scratch, Sage helps you get started, then gets out of the way. Sage is “delete-key
friendly” and it's easy to remove any features that you don't need.
We do typically recommend that you don't try Sage as your first WordPress theme and instead give it a shot once you've
got the basics covered. Underscores (_s) by Automattic is another popular starter theme, but it lacks any sort of front-end
workflow and doesn't require a sane minimum-version requirement for PHP. If Underscores is a “1,000 hour head start”,
Sage is a 10,000 hour head start.
What you'll find in Sage that you won't find in most other WordPress themes:
A modern build process
Modern PHP and requirements, along with PSR-2 coding standards (the most widely used and accepted coding
standards used in the PHP community) rather than WordPress coding standards
Better template file organization — no template files exist in the theme root
DRY templates with template inheritance
9
Why Sage?
Professionally maintained
At the time of writing, the Sage starter theme has over 9,000 stars and is the 15th most popular PHP project on GitHub. We
see over 4,000 new Sage projects being created every month based on GitHub and Packagist statistics.
Issues are squashed extremely fast, whether on GitHub or on Roots Discourse.
The project maintainers communicate daily and we're generally very accepting of feedback and improvements.
Widely used and trusted
There are over 50,000 live websites that are based on Sage. Some popular sites and brands using Sage include:
Amnesty International USA
Bacardi
D Magazine
Discovery Kids
GE
Goodwill
Hewlett Foundation
HotPads
Hulu
Japan.com
JetBlue
Jobvite
LendingTree
Mad Libs
Michael and Susan Dell Foundation
Morton Salt
Pied Piper (HBO)
Progresso
Quest Diagnostics
Redpoint Ventures
Sirius
Top Hat
University of Tennessee
UPS
US Government (Data.gov & US Embassy)
WebMD
Whitepages
Women Deliver
Zillow
Community support
Roots and Sage have a big support community behind it. Roots Discourse is a valuable resource with thousands of users
and topics. The forum is very active, and topics are usually responded to within 15 hours.
10
