Sage

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

Sage 9 is in active development and is only currently in alpha. The master branch tracks Sage 9 development. If you want a stable version, use Sage 8.

Features

Sass for stylesheets
ES6 for JavaScript
Webpack for compiling assets, optimizing images, and concatenating and minifying files
BrowserSync for synchronized browser testing
Bootstrap 4 for a front-end framework (can be removed or replaced)
Template inheritance with the theme wrapper

See a working example at roots-example-project.com.

Requirements

Make sure all dependencies have been installed before moving on:

PHP >= 5.5.x
Composer
Node.js >= 4.5

Theme installation

Install Sage using Composer from your WordPress themes directory (replace your-theme-name below with the name of your theme):

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

Theme structure

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

Theme setup

Edit src/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.

Build commands

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

Additional commands

npm run clean — Remove your dist/ folder
npm run lint — Run eslint against your assets and build scripts
composer test — Check your PHP for code smells with phpmd and PSR-2 compliance with phpcs

Using BrowserSync

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

If your local development URL is https://project-name.dev, update the file to read:

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

If you are not using Bedrock, update publicPath to reflect your folder structure:

...
  "publicPath": "/wp-content/themes/sage/"
...

By default, BrowserSync will use webpack's HMR, which won't trigger a page reload in your browser.

If you would like to force BrowserSync to reload the page whenever certain file types are edited, then add them to watch in assets/config.json.

...
  "watch": [
    "assets/scripts/**/*.js",
    "templates/**/*.php",
    "src/**/*.php"
  ],
...

Documentation

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

Sage 9 documention is currently in progress and can be viewed at https://github.com/roots/docs/tree/sage-9/sage.

Contributing

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

Community

Keep track of development and community news.

Participate on the Roots Discourse
Follow @rootswp on Twitter
Read and subscribe to the Roots Blog
Subscribe to the Roots Newsletter
Listen to the Roots Radio podcast

paulvanbuuren/sage