Skip to content
forked from roots/sage

WordPress starter theme based on HTML5 Boilerplate & Bootstrap

License

Notifications You must be signed in to change notification settings

JulienMelissas/sage

 
 

Repository files navigation

Packagist devDependency Status Build Status Sponsored by ES6.io

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

Sage 9 is in active development and is currently in beta. The master branch tracks Sage 9 development. If you want a stable version, use the latest Sage 8 release.

Features

  • Sass for stylesheets
  • ES6 for JavaScript
  • Webpack for compiling assets, optimizing images, and concatenating and minifying files
  • Browsersync for synchronized browser testing
  • Laravel's Blade as a templating engine
  • CSS framework options:
  • Font Awesome (optional)

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

Requirements

Make sure all dependencies have been installed before moving on:

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 dev-master

During theme installation you will have the options to:

  • Update theme headers (theme name, description, author, etc.)
  • Select a CSS framework (Bootstrap, Foundation, none)
  • Add Font Awesome
  • Configure Browsersync (path to theme, local development URL)

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/         # → 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)

Theme setup

Edit src/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, 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 yarn:

# @ themes/your-theme-name/
$ yarn

You now have all the necessary dependencies to run the build process.

Build commands

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

Additional commands

  • yarn run rmdist — Remove your dist/ folder
  • yarn run lint — Run ESLint against your assets and build scripts
  • composer test — Check your PHP for PSR-2 compliance with phpcs

Using Browsersync

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"
  ],
...

Documentation

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

Sage 9 documentation 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.

About

WordPress starter theme based on HTML5 Boilerplate & Bootstrap

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 57.8%
  • JavaScript 25.9%
  • HTML 11.5%
  • CSS 4.8%