Skip to content

Commit

Permalink
Merge pull request #30 from roots/sage-9
Browse files Browse the repository at this point in the history 
[WIP] Docs for Sage 9
  • Loading branch information
@retlehs
retlehs committed Feb 7, 2018
2 parents 05fb9ef + e4770f6 commit ae133bf
Show file tree
Hide file tree
Showing 9 changed files with 302 additions and 154 deletions.
2 changes: 1 addition & 1 deletion sage/extending-customizing-sage.md
View file
Expand Up @@ -39,4 +39,4 @@ post_date: 2015-09-01 19:30:13

## Extending Sage

* [Sage + UnCSS](https://discourse.roots.io/t/sage-uncss/5015) — UnCSS is a tool that removes unused CSS from your stylesheets
* [Sage + UnCSS](https://discourse.roots.io/t/sage-uncss/5015) — UnCSS is a tool that removes unused CSS from your stylesheets
80 changes: 59 additions & 21 deletions sage/theme-configuration-and-setup.md
View file
Expand Up @@ -9,33 +9,37 @@ permalink: >
https://roots.io/sage/docs/theme-configuration-and-setup/
published: true
---
`lib/setup.php` is used to enable/disable theme features and set configuration values. The theme features that can be disabled include:
`src/setup.php` is used to enqueue stylesheets and scripts, register support for theme features with <code>add_theme_support</code>, and register navigation menus and sidebars.

Clean up from [Soil](/plugins/soil):
## Stylesheets and scripts

add_theme_support('soil-clean-up');
Manage your front-end theme assets from the `src/setup.php` file:

Cleaner nav walker from [Soil](/plugins/soil):
```php
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style('sage/main.css', asset_path('styles/main.css'), false, null);
wp_enqueue_script('sage/main.js', asset_path('scripts/main.js'), ['jquery'], null, true);
}, 100);
```

add_theme_support('soil-nav-walker');
See [theme assets](/sage/docs/theme-development-and-building/#theme-assets) for more on how these assets are built. `asset_path` is a helper function that returns versioned asset filenames from the `dist/` directory.

Relative URLs from [Soil](/plugins/soil):
## Theme features

add_theme_support('soil-relative-urls');
### Soil

Nice search from [Soil](/plugins/soil):
We recommend using the [Soil](/plugins/soil) Plugin with every WordPress install for additional features:

add_theme_support('soil-nice-search');
* 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

Enable loading jQuery from [Soil](/plugins/soil):

add_theme_support('soil-jquery-cdn');

`lib/setup.php` is also used to register navigation menus, sidebars, and define theme support for WordPress core functionality such as post thumbnails, post formats, and HTML5 markup.

### Translations

The first part of the theme setup is making the theme translation available. Sage has [over 35 community translations](https://github.com/roots/sage-translations) available thanks to our contributors.
<small>&lowast;If Soil is installed and activated on your WordPress install, Sage will enable these features by default.</small>

### Title tag support

Expand All @@ -49,14 +53,48 @@ Sage registers a navigation menu called Primary Navigation. Additional menus sho

Post thumbnails are enabled with `add_theme_support('post-thumbnails')`, but they aren't output on any of the default templates. Add custom post thumbnail sizes with `add_image_size()`.

### Post formats
### HTML5 markup

Some WordPress post formats are enabled by default, but Sage doesn't provide any styling or templates for different post formats.
Sage enables HTML5 markup for captions, comment forms, comment lists, galleries, and the search form.

### Editor stylesheet

The TinyMCE editor in WordPress allows loading a custom stylesheet which is registered with `add_editor_style()`. The editor stylesheet is automatically generated from your main theme stylesheet when you run the build script.

### Register sidebars

Sage registers two sidebars by default: Primary & Footer. Add additional sidebars with `register_sidebar()`.
Sage registers two sidebars by default: Primary & Footer. Add additional sidebars with `register_sidebar()`.

## Theme structure

```shell
themes/your-theme-name/ # → Root of your Sage based theme
├── app/ # → 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
├── 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
│ ├── controllers/ # → Controller files
│ ├── 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)
```
11 changes: 8 additions & 3 deletions sage/theme-deployment.md
View file
Expand Up @@ -9,12 +9,17 @@ permalink: >
https://roots.io/sage/docs/theme-deployment/
published: true
---
## Generating production ready assets
To deploy a Sage theme you'll need to make sure two things are covered:

Generate production ready assets with `gulp --production`, which will build your assets without the source maps.
1. Run `composer install` from the theme directory on the remote server
2. Copy over production theme assets

## Generating production ready theme assets

Generate production ready assets with `yarn run build:production`, which will build your assets with versioned filenames.

If you use [Trellis](/trellis/), you can build your assets locally, then copy them to the remote server during deployment. [See the `build-before.yml` example hook](https://github.com/roots/trellis/blob/master/deploy-hooks/build-before.yml) in Trellis.

### Additional resources

[Build Steps and Deployment](http://austinpray.com/ops/2015/01/15/build-steps-and-deployment.html) by Austin Pray
[Build Steps and Deployment](http://austinpray.com/ops/2015/01/15/build-steps-and-deployment.html) by Austin Pray
178 changes: 133 additions & 45 deletions sage/theme-development-and-building.md
View file
Expand Up @@ -12,80 +12,168 @@ published: true
<p class="lead">These are the primary projects that make up the Sage workflow:</p>

<ul class="lead">
<li><h4><a href="http://gulpjs.com">gulp</a></h4><p><small>gulp is a streaming build tool. In previous versions of the theme we used Grunt for our build tool.</small></p></li>
<li><h4><a href="http://bower.io/">Bower</a></h4><p><small>Bower is a front-end package manager. Out of the box we pull in Bootstrap and Modernizr.</small></p></li>
<li><h4><a href="http://www.browsersync.io">BrowserSync</a></h4><p><small>BrowserSync keeps multiple browsers and devices synchronized while developing, along with injecting updated CSS and JS. In previous versions of the theme we used LiveReload for injecting assets.</small></p></li>
<li><h4><a href="https://github.com/austinpray/asset-builder">asset-builder</a></h4><p><small>asset-builder is the manifest file format that's used to collect all assets and put them in order.</small></p></li>
<li><h4><a href="https://github.com/taptapship/wiredep">wiredep</a></h4><p><small>wiredep is used to inject Sass and Less dependencies from Bower into the main theme stylesheet.</small></p></li>
<li><h4><a href="https://webpack.github.io/">Webpack</a></h4><p><small>is used as a build tool for compiling stylesheets, checking for JavaScript errors, optimizing images, and concatenating and minifying files. In previous versions of the theme we used Grunt and Gulp as our build tools.</small></p></li>
<li><h4><a href="https://www.npmjs.com/">npm</a></h4><p><small>npm is a front-end package manager. Sage uses npm to pull in Bootstrap and jQuery as dependencies. In previous versions of the theme we used Bower as our front-end package manager.</small></p></li>
<li><h4><a href="http://www.browsersync.io">BrowserSync</a> with Webpack Hot Module Replacement</h4><p><small>BrowserSync with WHR keeps multiple browsers and devices synchronized while developing, along with injecting updated CSS and JS. In previous versions of the theme we used LiveReload for injecting assets.</small></p></li>
</ul>

<div class="cta-product cta-product-sage well well-sage module"><a href="https://roots.io/books/theme-development-with-sage/" class="media"><div class="media-left"><img class="media-object" src="/app/uploads/theme-development-with-sage-cover-800x1035.png" alt="Sage book cover"></div><div class="media-body"><h4><span class="badge bg-white text-sage">Get the book</span> <br> <span class="text-sage">Theme Development with Sage</span></h4><p class="lead">A step-by-step guide to setting up a custom Sage starter theme.</p><p class="visible-md visible-lg">Build well organized &amp; easily maintained WordPress themes using a modern web development workflow.</p><p class="text-right"><button class="btn btn-primary">Buy</button></p></div></a></div>

## Installing project dependencies
## Available build commands

Your development machine must meet the following requirements to get started:
Run these script commands within your theme directory:

* Node.js >= 4.5.0
* `yarn run build` — Compile and optimize the files in your assets directory
* `yarn run build:production` — Compile assets for production
* `yarn run start` — Compile assets when file changes are made, start Browersync session

After installing [Node.js](http://nodejs.org/download/), we recommend that you update to the latest version of npm:
## Theme assets

The `config.json` file in the `assets` directory controls the different theme assets that get built. By default, Sage builds two JS files and one CSS file:

* `assets/stylesheets/main.scss` — primary theme CSS, barebones partials are imported to help get your styling started
* `assets/scripts/main.js` — primary theme JS
* `assets/scripts/customizer.js` — theme customizer JS, used only in the customizer

Look at `entry` in `assets/config.json` to see how they're built:

```json
"entry": {
"main": [
"./scripts/main.js",
"./styles/main.scss"
],
"customizer": [
"./scripts/customizer.js"
]
}
```
npm install -g npm@latest
```

From the command line:
To create additional CSS or JS files, you'll need to:

1. Create the files within the `assets/scripts/` or `assets/styles/` directories

2. Open `assets/config.json` and add the new files to `entry` in a new array. In the example below we've added `scripts/checkout.js`:

```json
"entry": {
"main": [
"./scripts/main.js",
"./styles/main.scss"
],
"customizer": [
"./scripts/customizer.js"
],
"checkout": [
"./scripts/checkout.js"
]
}
```

3. Enqueue the new file in `src/setup.php` In the example below we've added a conditional to only enqueue `scripts/checkout.js` on the checkout page:

```php
/**
* Theme assets
*/
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style('sage/main.css', asset_path('styles/main.css'), false, null);
wp_enqueue_script('sage/main.js', asset_path('scripts/main.js'), ['jquery'], null, true);

* Install gulp and Bower globally with `npm install -g gulp bower`
* Navigate to the theme directory, then run `npm install`
* Run `bower install`
if (is_page('checkout')) {
wp_enqueue_script('sage/checkout.js', asset_path('scripts/checkout.js'), ['jquery'], null, true);
}
}, 100);
```

You now have all the necessary dependencies to run the build process.
4. From the theme directory, run the build script:

## Available gulp commands
```sh
# web/app/themes/your-theme-name/
$ yarn run build
```

* `gulp` — Compile and optimize the files in your assets directory
* `gulp watch` — Compile assets when file changes are made
* `gulp --production` — Compile assets for production (no source maps)
### Images in template files

To use BrowserSync during `gulp watch` you need to update `devUrl` at the bottom of `assets/manifest.json` to reflect your local development hostname.
Use the `@asset` directive to call images from template files:

## Adding front-end packages with Bower
```php
<img src="@asset('images/example.jpg')">
```

### Images in CSS
CSS files and images are sibling folders, so you can reference images in CSS:
```css
.background {
background-image: url(../images/image.jpg);
}
```

## 3rd party packages

Example of how to add 3rd party packages* and have them included in the theme:

Install Bower packages with `bower install --save package-name`. Using the `--save` flag will add the package into your project's `bower.json` dependencies. asset-builder uses [main-bower-files](https://github.com/ck86/main-bower-files) to read your `bower.json` and automatically collect CSS and JS from files defined in the `main` property from your included Bower packages. You can override the behavior if you add an overrides property to your own `bower.json`. You can see overrides in action by opening `bower.json`.
1. From the theme directory, run:

## The asset pipeline
```shell
# @ themes/your-theme-name/
$ yarn add <package name>

The `manifest.json` file in the `assets/` directory is used by asset-builder to build out the CSS and JS files that are used by the theme.
# Install Slick carousel:
$ yarn add slick-carousel
```

<div class="well well-sage module">
<p>The <a href="https://github.com/austinpray/asset-builder#help">asset-builder documentation</a> has examples, troubleshooting tips, and the manifest file specification.</p>
</div>
2. Open up `main.js` and `main.scss` to add the entry points for the package. If you're using the Slick Carousel then your theme JS and CSS would look like:

### Theme stylesheets
```js
/** import external dependencies */
import 'jquery';
import 'bootstrap/dist/js/bootstrap';

Sage includes one primary stylesheet: `dist/styles/main.css`. `main.css` is built from `assets/styles/main.scss`.
// Import Slick
import 'slick-carousel/slick/slick.min';
```

In `main.scss`:
```scss
/* sage/assets/styles/main.scss */
@import "common/variables";

* wiredep is used to inject Sass dependencies from Bower
* Barebones partials are imported to help get your styling started
// Import npm dependencies
@import "~bootstrap/scss/bootstrap";
@import "~font-awesome/scss/font-awesome";
// Import Slick
@import "~slick-carousel/slick/slick.scss";
@import "~slick-carousel/slick/slick-theme.scss";
```

Any `main` CSS dependencies from Bower packages are also included in the primary stylesheet.
3. After running `yarn run build` from the theme directory, your package will be built with your theme assets. The `dist` folder will contain a `_/node_modules/` directory that has any assets referenced from your packages. The compiled CSS and JS will reference these assets without having to manually edit paths. ✨

The editor stylesheet, which is used by TinyMCE in the WordPress visual editor, is generated from your primary theme stylesheet.
4. Running `yarn run build:production` will fail if 3rd party package's relative paths are not configured before imported. In example to load Slick Carousel's paths add the following line in your common/_variables.scss file:

<div class="well well-sage module">
<p><b>Tip:</b> You can use the <code>manifest.json</code> file to include CSS from WordPress plugins in your theme's primary stylesheet by defining the path to the vendor CSS file with the <code>vendor</code> property. See the <a href="https://github.com/austinpray/asset-builder#help">asset-builder documentation</a> for examples, troubleshooting tips, and the manifest file specification.</p>
</div>
```scss
/* sage/assets/styles/common/_variables.scss */
// Slick Carousel font path
$slick-font-path: "~slick-carousel/slick/fonts/";

### Theme scripts
// Slick Carousel ajax-loader.gif path
$slick-loader-path: "~slick-carousel/slick/";
```

Sage includes one primary JavaScript file: `dist/scripts/main.js`. `main.js` is built from `assets/scripts/main.js`.
<small>&lowast;Note: Wordpress Plugins are installed elsewhere or with Composer when using [Bedrock](/bedrock/docs/composer)</small>

Any `main` JS dependencies from Bower packages are also included in the primary JavaScript file.
### Additional examples

Sage also loads jQuery and Modernizr before the primary JavaScript file.
#### Font Awesome

<div class="well well-sage module">
<p><b>Tip:</b> You can use the <code>manifest.json</code> file to include JS from WordPress plugins in your theme's primary JavaScript file by defining the path to the vendor JS file with the <code>vendor</code> property. See the <a href="https://github.com/austinpray/asset-builder#help">asset-builder documentation</a> for examples, troubleshooting tips, and the manifest file specification.</p>
</div>
```sh
# @ themes/your-theme-name/
$ yarn add font-awesome
```

```scss
/* sage/assets/styles/main.scss */
@import "common/variables";

// Import Font Awesome from node_modules
@import "~font-awesome/scss/font-awesome.scss";
```

0 comments on commit ae133bf

Please sign in to comment.