168 lines
6.7 KiB
Markdown
168 lines
6.7 KiB
Markdown
# [Sage](https://roots.io/sage/)
|
|
[](https://packagist.org/packages/roots/sage)
|
|
[](https://david-dm.org/roots/sage#info=devDependencies)
|
|
[](https://travis-ci.org/roots/sage)
|
|
[](https://roots.io/r/es6)
|
|
|
|
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](https://github.com/roots/sage/releases/latest).**
|
|
|
|
## Features
|
|
|
|
* Sass for stylesheets
|
|
* ES6 for JavaScript
|
|
* [Webpack](https://webpack.github.io/) for compiling assets, optimizing images, and concatenating and minifying files
|
|
* [Browsersync](http://www.browsersync.io/) for synchronized browser testing
|
|
* [Laravel's Blade](https://laravel.com/docs/5.3/blade) as a templating engine
|
|
* CSS framework options:
|
|
* [Bootstrap 4](http://getbootstrap.com/)
|
|
* [Foundation](http://foundation.zurb.com/)
|
|
* None (blank slate)
|
|
* Font Awesome (optional)
|
|
|
|
See a working example at [roots-example-project.com](https://roots-example-project.com/).
|
|
|
|
## Requirements
|
|
|
|
Make sure all dependencies have been installed before moving on:
|
|
|
|
* [WordPress](https://wordpress.org/) >= 4.7
|
|
* [PHP](http://php.net/manual/en/install.php) >= 5.6.4
|
|
* [Composer](https://getcomposer.org/download/)
|
|
* [Node.js](http://nodejs.org/) >= 6.9.x
|
|
* [Yarn](https://yarnpkg.com/en/docs/install)
|
|
|
|
## Theme installation
|
|
|
|
Install Sage using Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme):
|
|
|
|
```shell
|
|
# @ 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
|
|
|
|
```shell
|
|
themes/your-theme-name/ # → Root of your Sage based theme
|
|
├── 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
|
|
├── 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
|
|
│ └── views/ # → 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](https://webpack.github.io/) as a build tool and [npm](https://www.npmjs.com/) 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`:
|
|
|
|
```shell
|
|
# @ 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:
|
|
```json
|
|
...
|
|
"devUrl": "https://project-name.dev",
|
|
...
|
|
```
|
|
|
|
If you are not using [Bedrock](https://roots.io/bedrock/), update `publicPath` to reflect your folder structure:
|
|
|
|
```json
|
|
...
|
|
"publicPath": "/wp-content/themes/sage"
|
|
...
|
|
```
|
|
|
|
By default, Browsersync will use webpack's [HMR](https://webpack.github.io/docs/hot-module-replacement.html), 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`.
|
|
|
|
```json
|
|
...
|
|
"watch": [
|
|
"assets/scripts/**/*.js",
|
|
"templates/**/*.php",
|
|
"src/**/*.php"
|
|
],
|
|
...
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Sage 8 documentation is available at [https://roots.io/sage/docs/](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](https://github.com/roots/docs/tree/sage-9/sage).
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome from everyone. We have [contributing guidelines](https://github.com/roots/guidelines/blob/master/CONTRIBUTING.md) to help you get started.
|
|
|
|
## Community
|
|
|
|
Keep track of development and community news.
|
|
|
|
* Participate on the [Roots Discourse](https://discourse.roots.io/)
|
|
* Follow [@rootswp on Twitter](https://twitter.com/rootswp)
|
|
* Read and subscribe to the [Roots Blog](https://roots.io/blog/)
|
|
* Subscribe to the [Roots Newsletter](https://roots.io/subscribe/)
|
|
* Listen to the [Roots Radio podcast](https://roots.io/podcast/)
|