Modern WordPress Theme Development with Sage 9


Here is an Beta release of a talk I’m giving at WordCampDC 2017. The slides will be here.

Feel free to ping me for critiques and requests. Cheers!


  1. Open
    1. Tonal shift: Appreciation, not Apologies
    2. Resources
    3. Likert Tests
    4. Defining ‘Modern’
    5. Sage is a great thing, not the great thing
  2. Sage Background
    1. What: A starter theme
    2. Who:
    3. When and Where: Examples in the wild
    4. How: Twelve Factor Applications
    5. Why: Joy of Programming
  3. Sage Dependencies
    1. Git
    2. Composer
    3. Directory Structure
    4. Yarn and NPM
    5. WebPack
  4. Sage Templating
    1. Build with Browsersync
    2. Theme Setup
    3. Bootstrap 4
    4. Blade
    5. JavaScript Routing
  5. Close
    1. Twelve Factor Applications
    2. Modernization, Gutenberg and the future
    3. Russian Identity
    4. Make Greatness great again
    5. Me

Previous Flow, Notes and Ideas (delete)

  1. Why use Modern Practices?
    1. Story of Peter the Great
      1. Upset the Boyars
      2. “Boy-are they in for a surprise”
      3. Who are your Boyars?
      4. Tradition is familiar and comfortable, it may even be efficient, is it holding you back?
      5. Of course as always, this leads us down the Allegory of the Cave:
      6. New ideas and habits are hard. Especially at any sort of scale. Culture is hard.
      7. Growth is painful becomes it comes at a serious cost of sacrifice. You must weigh your options, giving up something that is perhaps more valuable. This is risk.
      8. I can’t say that it will be easy, but I can say that it will be worth it. Obviously success will make it worthwhile, but  even if the trials don’t go well the pain of trying something new will make you a better developer, thinker and do-er in the long run. Practice makes perfect.
      9. Yadda yadda yadda. Whatever doesn’t kill you makes you stronger.
      10. Do it right the first time.
      11. Learn new things even if they don’t seem immediately valuable.
      12. It is easier to wait until the choice to modernize is made for you, but that isn’t exactly brave or daring. Don’t wait until it is too late.
      13. Even if there is only a myth of ‘Great’ people of history, it is the myth that moves us. Somebody, somewhere along the line has to take a chance and change something.
    2. Modernity takes sacrifice: investment and risk
    3. Dare to be great
    4. Stand on the shoulders of giants: improve the ideas of others
    5. Some sort of connection to WordPress Core
      1. PHP looks to the past (is this true?)
      2. JS looks to the future


Tonal Shift: Appreciation, not apologies

It is generally always difficult to remain cool and collected with a major talk approaching. As I was preparing and researching for this talk, I kept uncovering more and more things that I didn’t know about.

Thank you for your cooperation and interest.

Likert Tests

I always like to add an experimental element to my presentations. I’m not very fond of the ‘wise speaker at the podium’ mentality. Presentations should be a humble sharing of knowledge; the presentations should be dynamic and interactive.

It’s difficult to gauge audience interest ahead of time, but it’s perhaps the most critical thing you can do as a speaker. It’s a simple question: Who is in my audience? Why did they are here?

I set this as my intended audience: Experienced theme developers that have heard about ‘new’ stuff but haven’t taken the time to check it out. They are curious about new things, but are not sure what the new things are, or why they should invest the time.

Additionally though, I’m the last speaker in a very tiring two day stretch, and everyone is probably exhausted. So I want to try something gimmicky, but hopefully not too gimmicky.

How better to get to know your audience other than simply asking them who they are?

So let’s run a few fast surveys. I’m going to show a statement and count from 1-5. “One” means “Strongly Disagree”, “Three” is “Neutral” and “Five” means “Strongly Agree”. You simply raise your hand at the number that reflects your sentiment on the statement.

We’re going to move quickly, so no time for thinking, just go on instinct.

  • “I’m very tired”
  • “I’m familiar with the Likert Scale”
  • “I like it when new friends try to get to know me”
  • “I like being berated with aggressive questions by strangers in public”
  • “This is a gimmick”

Here are some statements to gauge familiarity with technical experience:

  • “I’m familiar with WordPress theme development”
  • “I’m familiar with the Sage theme”
  • “I’m familiar with Composer”
  • “I’m familiar with NPM”
  • “I’m familiar with Yarn”
  • “I’m familiar with Webpack”
  • “I’m familiar with Browsersync”
  • “I’m familiar with Bootstrap”
  • “I’m familiar with Blade Templates”
  • “I’m familiar with Twelve Factor application development”
  • “This is a useful gimmick”

I’ll post more statements as we move through the talk.


This is a brief overview of the Sage theme. It is impossible to really grok development information in a 25 minute talk. I’m hoping this exposes you to some new ideas; things you may have not considered before.

In that light, all of this material is collected online. There is a main blog post with detailed information about Sage and the build process.

Links and relevant resources are at the bottom of this post. These resources are also listed at the beginning of the slides.

Defining ‘Modern’

This is a presentation about ‘Modern Development Practices.’

The word ‘modern’ is used a lot historically to mean ‘better.’ I believe, for the most part, this is correct.

‘Modernity,’ in social and technical terms, is generally forward thinking, egalitarian and useful.

On a standard population adoption bell curve, there will always be a class of people who benefit from the current status-quo. They are resistant to change.

This reminds me of a lesson from college, the story of Peter the Great.


However, ‘Modern’ is not always best.

Improving practices and techniques takes risk and sacrifice.

Sage is a great thing, not the great thing

There is a lot of fashion and persuasion in software development. In a culture of innovation that is rapidly modernizing, many people are always looking for the next great thing.

‘Thought Leaders’ scramble to post strong opinions to build both their clicks and cliques.

I don’t know if the Sage theme is the best. I know I like it.

TODO: Finish this.

Sage Background

So what is the Sage theme then? Here is a the quick synopsis.

What: A WordPress Starter Theme

Not a child theme, but a starter theme. Fork it when you are first starting your site.

Who: and You

When and Where: Sage in the wild

In 2016 while at CHIEF in DC we built the Lighting Global website with Sage 8 for the World Bank.

At CHIEF we built the Lighting Global website with Sage 8

I use Sage 9 for this very website,

How: Twelve Factor Applications


  • Exposure to New Ideas
  • Sustainability with Happier Developers
  • Better Productivity with Flow
  • Quality Control with High Quality Habits
  • Joy of Programming

Sage Dependencies


In the themes directory run the following command:

git clone THEMENAME

This will also add a new .git directory to your new theme.

TODO: Why should the theme code be part of the project repo? Links?

Remove the sage .git directory with

rm -rf THEMENAME/.git

Here is a quick image of me creating my new wcdc17 theme with the above commands.

In the themes directory, clone sage as a new theme, remove the unneeded git history and take a look at the files inside.


TODO: What is Composer? Why use it?

A common problem with development projects is that they get very large in size.

This is especially true for when using modern development techniques. You may want to ‘lint’ your code  which may have large binaries.

When sharing a codebase with other developers on your team

You might be familiar with the concept of Gems and Bundler for Ruby, Packages and NPM for JavaScript, or Homebrew for macOS.

A ‘package manager’ is simple and convenient way to attach 3rd party developer libraries to your project

Composer is the main package manager for PHP. You may have to install Composer if it is not already on your main operating system.

Inside your new theme, from the command line run composer install.

This creates a new vendor directory.

TODO: What’s all in the vendor directory?

Sage Theme Directory Structure

TODO: Missing style.css and functions.php

A typical WordPress theme needs a style.css and a functions.php.

TODO: What’s all in the resources directory?

Rename the theme

it’s in resources, what’s the deal with that?

“Think outside the box gotcha”

“The ordinary rules might not be what you think, and they may not always apply”


Yarn and NPM

Run yarn to download all npm packages into node_modules

TODO: Show fancy cli downloader.

You may need to run npm upgrade --global yarn, as yarn updates frequently

TODO: Show new ‘node_modules’ folder.


Set Development Config Settings

In resources/assets/config.json set the publicPath and devUrl keys to match your system.

TODO: Why do we have to do this? Webpack?

publicPath should probably be set to /wp-content/themes/THEMENAME. Mine is set as app/themes/wcdc because I use the Bedrock architecture (another Roots solution I recommend).

devUrl should be set to the url alias you have set for your development environment. Mine is set to

TODO: Do they have to do this?


Sage Templating

Build with Browsersync

Turn it on!

Now you can run yarn run start and Webpack will start running in your browser.

TODO: What is actually gong on here? “Webpack” isn’t running in the browser.

TODO: What else do they get with Webpack?


Theme Setup

Bootstrap 4

Bootstrap 4 is a full rewrite of the very popular CSS grid system. It has been in development for 2 years now. It’s currently in it’s last alpha release, and will be in beta soon. Probably.

In my opinion, for all general purposes it is good enough to start using for a production environment. Your mileage may vary though and you’ll need to decide for yourself.

Here is a quick list of major changes happening in Bootstrap 4

Browser Support

IE8, IE9 and iOS 6 are no longer supported.

Grid System

Flexbox and ‘sm’ size grid tier



And More…



Blade is a templating system created by Laravel, a PHP application framework.


JavaScript Routing


Twelve Factor Applications

Modernization, Gutenberg and the future

Modern Identity

Make Greatness great again



Leave a Reply

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