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:
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 dev-sage-9
Then activate the theme via wp-cli:
# @ example.com/site
$ wp theme activate your-theme-name
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
Edit src/lib/setup.php
to enable or disable theme features, setup navigation menus, post thumbnail sizes, post formats, 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 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.
npm run build
— Compile and optimize the files in your assets directorynpm run watch
— Compile assets when file changes are made, start BrowerSync sessionnpm run build:production
— Compile assets for production
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",
...
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.
- 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