Sage

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

Features

Sass for stylesheets
Modern JavaScript
Webpack for compiling assets, optimizing images, and concatenating and minifying files
Browsersync for synchronized browser testing
Blade as a templating engine
Controller for passing data to Blade templates
CSS framework (optional): Bootstrap 4, Bulma, Foundation, Tachyons, Tailwind

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

Requirements

Make sure all dependencies have been installed before moving on:

WordPress >= 4.7
PHP >= 7.1.3 (with php-mbstring enabled)
Composer
Node.js >= 8.0.0
Yarn

Theme installation

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

To install the latest development version of Sage, add dev-master to the end of the command:

$ composer create-project roots/sage your-theme-name dev-master

During theme installation you will have options to update style.css theme headers, select a CSS framework, and configure Browsersync.

Theme structure

themes/your-theme-name/   #  Root of your Sage based theme
 app/                  #  Theme PHP
    Controllers/      #  Controller files
    admin.php         #  Theme customizer setup
    filters.php       #  Theme filters
    helpers.php       #  Helper functions
    setup.php         #  Theme setup
 composer.json         #  Autoloading for `app/` files
 composer.lock         #  Composer lock file (never edit)
 dist/                 #  Built theme assets (never edit)
 node_modules/         #  Node.js packages (never edit)
 package.json          #  Node.js dependencies and scripts
 resources/            #  Theme assets and templates
    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
    functions.php     #  Composer autoloader, theme includes
    index.php         #  Never manually edit
    screenshot.png    #  Theme screenshot for WP admin
    style.css         #  Theme meta information
    views/            #  Theme templates
        layouts/      #  Base templates
        partials/     #  Partial templates
 vendor/               #  Composer packages (never edit)

Theme setup

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

Theme development

Run yarn from the theme directory to install dependencies
Update resources/assets/config.json settings:
- devUrl should reflect your local development hostname
- publicPath should reflect your WordPress folder structure (/wp-content/themes/sage for non-Bedrock installs)

Build commands

yarn start Compile assets when file changes are made, start Browsersync session
yarn build Compile and optimize the files in your assets directory
yarn build:production Compile assets for production