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 the latest Sage 8 release.
- Sass for stylesheets
- 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.
Make sure all dependencies have been installed before moving on:
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
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)
src/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, post formats, and sidebars.
From the command line on your host machine (not on your Vagrant development box), navigate to the theme directory then run
# @ example.com/site/web/app/themes/your-theme-name $ npm install
You now have all the necessary dependencies to run the build process.
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
npm run clean— Remove your
npm run lint— Run eslint against your assets and build scripts
composer test— Check your PHP for code smells with
phpmdand PSR-2 compliance with
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": [ "assets/scripts/**/*.js", "templates/**/*.php", "src/**/*.php" ], ...
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.
Contributions are welcome from everyone. We have contributing guidelines to help you get started.
Keep track of development and community news.