WordPress starter theme with a modern development workflow
PHP JavaScript CSS
Latest commit ce679c3 Aug 31, 2016 @QWp6t QWp6t committed on GitHub Merge pull request #1701 from Jeger/update-readme-browsersync
README updated for running browsersync without bedrock
Failed to load latest commit information.
.github Added contributing guidelines link to readme Jul 21, 2016
assets Set dynamically aboslute public path on 'npm run watch'; fix http/htt… ( Aug 26, 2016
src Fix path to stylesheet in add_editor_style Jul 23, 2016
templates Remove HTML comments from wrapper Aug 4, 2016
.editorconfig Only use root editorconfig, allow warnings in travis Mar 11, 2016
.eslintrc Squashing asset pipeline bugs and other stuff Aug 13, 2016
.gitattributes Ignore .github dir and .travis.yml for Composer installs Aug 14, 2016
.gitignore gitignore composer vendor directory Feb 14, 2016
.travis.yml Add `npm prune` to Travis CI Jun 8, 2016
CHANGELOG.md Sage 9.0.0-alpha.1 Aug 30, 2016
LICENSE.md Formatting, adding/updating links Nov 8, 2013
README.md README updated for running browsersync without bedrock Aug 31, 2016
composer.json Use Composer to run PHPCS and PHPMD tests Apr 3, 2016
composer.lock Use Composer to run PHPCS and PHPMD tests Apr 3, 2016
functions.php Fix display of theme name in Customizer Jul 16, 2016
index.php Only use root editorconfig, allow warnings in travis Mar 11, 2016
package.json Sage 9.0.0-alpha.1 Aug 30, 2016
phpcs.xml All function braces need to be on new line Mar 11, 2016
screenshot.png Update screenshot resolution to 880x660, change to blank image Mar 12, 2014
style.css Sage 9.0.0-alpha.1 Aug 30, 2016
watch.js Set dynamically aboslute public path on 'npm run watch'; fix http/htt… ( Aug 26, 2016
webpack.config.js Set dynamically aboslute public path on 'npm run watch'; fix http/htt… ( Aug 26, 2016



Packagist devDependency Status Build Status

Sage is a WordPress starter theme with a modern development workflow.

Write stylesheets with Sass, automatically check your JavaScript for errors, optimize images, enable synchronized browser testing, and more.


  • Webpack is used as a build tool for compiling stylesheets, checking for JavaScript errors, optimizing images, and concatenating and minifying files
  • BrowserSync for keeping multiple browsers and devices synchronized while testing, along with injecting updated CSS and JS into your browser while you're developing
  • Bootstrap
  • Template inheritance with the theme wrapper
  • ARIA roles and microformats
  • Posts use the hNews microformat
  • Multilingual ready and over 30 available community translations

Install the Soil plugin to enable additional recommended features:

  • Load jQuery from the jQuery CDN
  • Cleaner WordPress markup
  • Cleaner HTML output of navigation menus
  • Root relative URLs
  • Nice search
  • Google Analytics snippet from HTML5 Boilerplate
  • Move all JS to the footer
  • Disable trackbacks and pingbacks

See a complete working example in the roots-example-project.com repo.


Make sure all dependencies have been installed before moving on:

Theme installation

From the command line, run the following commands from the root of your WordPress site (where composer.json exists). These instructions assume you're using a Bedrock-based WordPress setup. If you're using Vagrant, make sure to run these commands from the Vagrant box (vagrant ssh). Create a new theme based on Sage by using Composer's create-project:

# @ example.com/site
$ composer create-project roots/sage web/app/themes/your-theme-name 9.0.0-alpha.1

Then activate the theme via wp-cli:

# @ example.com/site
$ wp theme activate your-theme-name

Theme structure

themes/theme-name/        # → Root of your Sage based theme
├── assets                # → Front-end assets
│   ├── config.json       # → Settings for compiled assets
│   ├── fonts/            # → Theme fonts
│   ├── images/           # → Theme images
│   ├── scripts/          # → Theme JS
│   └── styles/           # → Theme stylesheets
├── composer.json         # → Autoloading for `src/` files
├── composer.lock         # → Composer lock file (never manually edit)
├── dist/                 # → Built theme assets (never manually edit)
├── functions.php         # → Never manually edit
├── index.php             # → Never manually edit
├── node_modules/         # → Node.js packages (never manually edit)
├── package.json          # → Node.js dependencies and scripts
├── screenshot.png        # → Theme screenshot for WP admin
├── src/                  # → Theme PHP
├── style.css             # → Theme meta information
├── templates/            # → Theme templates
│   ├── layouts/          # → Base templates
│   └── partials/         # → Partial templates
├── vendor/               # → Composer packages (never manually edit)
├── watch.js              # → Webpack/BrowserSync watch config
└── webpack.config.js     # → Webpack config

Theme setup

Edit src/lib/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, post formats, and sidebars.

Theme development

Sage uses Webpack as a build tool and npm to manage front-end packages.

Install dependencies

From the command line on your host machine (not on your Vagrant development box), navigate to the theme directory then run npm install:

# @ example.com/site/web/app/themes/your-theme-name
$ npm install

You now have all the necessary dependencies to run the build process.

Available build commands

  • npm run build — Compile and optimize the files in your assets directory
  • npm run watch — Compile assets when file changes are made, start BrowerSync session
  • npm run build:production — Compile assets for production

Using BrowserSync

To use BrowserSync during npm watch you need to update devUrl at the bottom of assets/config.json to reflect your local development hostname.

For example, if your local development URL is https://project-name.dev you would update the file to read:

  "devUrl": "https://project-name.dev",

If you are not using Bedrock, you should also update publicPatch to reflect your folder strutcture.

If your theme is placed in folder called sage in a standard wordpress setup it should look like this:

  "output": {
    "path": "dist",
    "publicPath": "/wp-content/themes/sage/dist/"


Sage documentation is available at https://roots.io/sage/docs/.


Contributions are welcome from everyone. We have contributing guidelines to help you get started.


Keep track of development and community news.