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
- 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)
- Laravel's Blade as a templating engine
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):
# @ app/themes/ or wp-content/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/ # → Blade implementation, 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)
Edit src/setup.php
to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.
Sage uses Webpack as a build tool and npm to manage front-end packages.
From the command line on your host machine (not on your Vagrant development box), navigate to the theme directory then run yarn
:
# @ example.com/site/web/app/themes/your-theme-name
$ yarn
You now have all the necessary dependencies to run the build process.
yarn run start
— Compile assets when file changes are made, start Browsersync sessionyarn run build
— Compile and optimize the files in your assets directoryyarn run build:production
— Compile assets for production
yarn run clean
— Remove yourdist/
folderyarn run lint
— Run eslint against your assets and build scriptscomposer test
— Check your PHP for code smells withphpmd
and PSR-2 compliance withphpcs
To use Browsersync 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"
],
...
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.
- 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