Merge branch 'develop'

* develop:
  Documentation update
  Proper cssnano integration
  Version bump and dependency update
  Deps update and version bump

gulpconfig.js

@@ -85,8 +85,12 @@ module.exports = {
     , dest: build
     }
   , compiler: 'libsass' // Choose a Sass compiler: 'libsass' or 'rubysass'
-  , autoprefixer: { browsers: ['> 3%', 'last 2 versions', 'ie 9', 'ios 6', 'android 4'] } // This tool is magic and you should use it in all your projects :)
-  , minify: { safe: true }
+  , cssnano: {
+      autoprefixer: {
+        add: true
+      , browsers: ['> 3%', 'last 2 versions', 'ie 9', 'ios 6', 'android 4'] // This tool is magic and you should use it in all your projects :)
+      }
+    }
   , rubySass: { // Requires the Ruby implementation of Sass; run `gem install sass` if you use this; Compass is *not* included by default
       loadPath: ['./src/scss', bower, modules] // Adds Bower and npm directories to the load path so you can @import directly
     , precision: 6

gulpfile.js/tasks/styles.js

@@ -4,29 +4,25 @@ var gulp          = require('gulp')
   , gutil         = require('gulp-util')
   , plugins       = require('gulp-load-plugins')({ camelize: true })
   , config        = require('../../gulpconfig').styles
-  , autoprefixer  = require('autoprefixer')
-  , processors    = [autoprefixer(config.autoprefixer)] // Add additional PostCSS plugins to this array as needed
 ;
 
-// Build stylesheets from source Sass files, autoprefix, and write source maps (for debugging) with rubySass
+// Build stylesheets from source Sass files, post-process, and write source maps (for debugging) with rubySass
 gulp.task('styles-rubysass', function() {
   return plugins.rubySass(config.build.src, config.rubySass)
   .on('error', gutil.log) // Log errors instead of killing the process
-  .pipe(plugins.postcss(processors))
-  .pipe(plugins.cssnano(config.minify))
-  .pipe(plugins.sourcemaps.write('./')) // No need to init; this is set in the configuration
-  .pipe(gulp.dest(config.build.dest)); // Drops the unminified CSS file into the `build` folder
+  .pipe(plugins.cssnano(config.cssnano)) // Post-process CSS (minify, autoprefix, etc.)
+  .pipe(plugins.sourcemaps.write('./')) // Write an external sourcemap; no need to initialize with rubysass as this is already done in the configuration
+  .pipe(gulp.dest(config.build.dest)); // Render the final CSS file(s) into the `build` folder
 });
 
-// Build stylesheets from source Sass files, autoprefix, and write source maps (for debugging) with libsass
+// Build stylesheets from source Sass files, post-process, and write source maps (for debugging) with libsass
 gulp.task('styles-libsass', function() {
   return gulp.src(config.build.src)
-  .pipe(plugins.sourcemaps.init())
+  .pipe(plugins.sourcemaps.init()) // Note that sourcemaps need to be initialized with libsass
   .pipe(plugins.sass(config.libsass))
-  .pipe(plugins.postcss(processors))
-  .pipe(plugins.cssnano(config.minify))
-  .pipe(plugins.sourcemaps.write('./')) // Writes an external sourcemap
-  .pipe(gulp.dest(config.build.dest)); // Drops the unminified CSS file into the `build` folder
+  .pipe(plugins.cssnano(config.cssnano))
+  .pipe(plugins.sourcemaps.write('./'))
+  .pipe(gulp.dest(config.build.dest));
 });
 
 // Easily configure the Sass compiler from `/gulpconfig.js`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "wordpress-gulp-starter-kit",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "A starter kit for developing WordPress themes with Gulp",
   "homepage": "https://github.com/synapticism/wordpress-gulp-starter-kit",
   "repository": {
@@ -25,21 +25,19 @@
   "main": "gulpfile.js",
   "private": true,
   "devDependencies": {
-    "autoprefixer": "^6.3.6",
-    "browser-sync": "^2.12.3",
+    "browser-sync": "^2.13.0",
     "del": "^2.2.0",
     "gulp": "^3.9.1",
     "gulp-changed": "^1.3.0",
     "gulp-concat": "^2.6.0",
-    "gulp-cssnano": "^2.1.1",
-    "gulp-imagemin": "^2.4.0",
-    "gulp-jshint": "^2.0.0",
+    "gulp-cssnano": "^2.1.2",
+    "gulp-imagemin": "^3.0.1",
+    "gulp-jshint": "^2.0.1",
     "gulp-livereload": "^3.8.1",
-    "gulp-load-plugins": "^1.2.2",
-    "gulp-postcss": "^6.1.0",
+    "gulp-load-plugins": "^1.2.4",
     "gulp-rename": "^1.2.2",
     "gulp-ruby-sass": "^2.0.6",
-    "gulp-sass": "^2.2.0",
+    "gulp-sass": "^2.3.1",
     "gulp-sourcemaps": "^1.6.0",
     "gulp-uglify": "^1.5.3",
     "gulp-util": "^3.0.7",

readme.md

@@ -10,6 +10,7 @@ Why use this project instead of any of the alternatives? A few advantages:
 * You should be able to easily drop your own theme into the `src` folder and start hacking without much additional setup.
 * Documentation and comments in the code assume a novice level of understanding.
 * Builds on existing WordPress and Gulp best practices without doing anything too crazy.
+* Includes several JS and Sass integrations to show you some of the possibilities. All of these are easily removed.
 * This kind of workflow will save you a ton of time and help you make better, more readily-optimized themes once you learn how it all works.
 
 
@@ -36,7 +37,7 @@ If you're already up and running with most of the usual Node ecosystem tools thi
 ## SETUP
 
 * Edit `gulpconfig.js` and, *at the very least*, change the `project` variable to match the name of your theme. If you like the way this workflow is setup you shouldn't need to edit any of the files under `gulpfile.js/tasks` just yet.
-* Install all dependencies by running `npm install`. This will fetch all dependencies listed in `package.json` (which includes front-end JavaScript packages and back-end tools like Gulp plugins and [BrowserSync](http://www.browsersync.io/)).
+* Install all dependencies by running `npm install`. This will fetch all dependencies listed in `package.json` (which includes front-end JavaScript packages and back-end tools like Gulp plugins and [BrowserSync](http://www.browsersync.io/)). You may see warnings about deprecated packages and what-not; that's probably fine, just keep going!
 * [BrowserSync](http://www.browsersync.io/) setup: assuming you have a local development environment setup all you should need to do is enter the URL into the `proxy` setting in `gulpconfig.js`. Why use BrowserSync? It's fast, awesome, and allows for simultaneous responsive development across multiple devices.
 * [LiveReload](http://livereload.com/) setup: install a browser extension for [Chrome](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) or Firefox. Why use LiveReload? It does the job without complications or additional setup after the extension is installed.
 * This build process assumes you're up and running with [source maps for both JavaScript and Sass](http://blog.teamtreehouse.com/introduction-source-maps). You may need to configure your browser or debugging environment to make sense of the minified files generated by Gulp!
@@ -48,7 +49,7 @@ If you're already up and running with most of the usual Node ecosystem tools thi
 
 Previously this project shipped without a working theme included. I figured that with all the great starter themes out there (for instance, [_s](https://github.com/Automattic/_s), [Roots](https://github.com/roots/roots), and [Bones](https://github.com/eddiemachado/bones)) it wouldn't be hard to drop one in and start theming. I don't personally use any of these so I was a little surprised to discover how tricky this can be. Starter themes, despite their "bare bones" reputation, are often bulky and opinionated. Some even ship with their own build processes already in place!
 
-It seems there is a need for what I'd call a *minimum viable theme*: a truly bare bones WordPress starter theme featuring only the essentials to get up and running, something that you can assess at a glance. For the purposes of this project I have created such a theme, tentatively named `voidx`. It isn't pretty and isn't up to [WordPress standards](https://wordpress.org/plugins/theme-check/) but it works well enough to show off some of the power of this workflow. Feel free to play with or discard it as you wish. All files under `src` can be replaced by your own files, you just have to be sure to wire things up properly in the `gulpconfig.js` file if you swap in your own stuff. I've already integrated [timeago](http://timeago.yarp.com/), a simple script to transform timestamps into something more human-readable, but this is easily removed if you don't like it (which is sort of the point of having such scaffolding, so you can easily swap stuff in and out).
+It seems there is a need for what I'd call a *minimum viable theme*: a truly bare bones WordPress starter theme featuring only the essentials to get up and running, something that you can assess at a glance. For the purposes of this project I have created such a theme, tentatively named `voidx`. It isn't pretty and isn't up to [WordPress standards](https://wordpress.org/plugins/theme-check/) but it works well enough to show off some of the power of this workflow. Feel free to play with or discard it as you wish. All files under `src` can be replaced by your own files, you just have to be sure to wire things up properly in the `gulpconfig.js` file if you swap in your own stuff. Several scripts have already been integrated to show you how it's done, but these are easily if you don't like 'em (which is sort of the point of having such scaffolding, so you can easily swap stuff in and out).
 
 There are two components worth a closer look:
 
@@ -84,7 +85,7 @@ Configuration is handled by a single file: `gulpconfig.js`. If you leave the dir
 * [BrowserSync](http://www.browsersync.io/) settings: if you are developing on a local web server you will want to enter the URL into `browsersync.proxy` and then change `watch.watcher` to `browsersync` to take it for a test drive. You'll know it's working when you run `gulp` and a new browser opens with a live copy of your web site. Make changes to any of the Sass files and they should be shown on the page almost immediately. Of course, BrowserSync really shines when you connect a mobile device to your development server, but for that you're on your own ;)
 * Script settings: draw your attention to `scripts.bundles` and `scripts.chunks`. This feature is essentially a poor man's [Browserify](http://browserify.org/) or [Webpack](https://webpack.github.io/). By defining different "chunks" (script files that combine to provide a particular feature) and "bundles" (chunks that combine to provide feature sets) you can generate an assortment of files that can be efficiently and intelligently loaded through your WordPress theme. This approach has its limitations, of course, particularly when dependencies are shared between scripts, but it should be of use to many WordPress theme developers.
 
-Interested in adding new Gulp plugins to your build system? A full tutorial is out of scope for this project but it really shouldn't be all that hard to figure out. In brief, install a plugin with `npm install [package] --save-dev`, require it in a suitable task file, add something to the configuration file if needed, and drop it into the pipeline somewhere. Some types of plugin are particularly easy to add, for instance anything listed on the [postcss.parts](http://postcss.parts/) web site (install, require, and add to the `processor` variable in `/gulpfile.js/tasks/styles.js`).
+Interested in adding new Gulp plugins to your build system? A full tutorial is out of scope for this project but it really shouldn't be all that hard to figure out. In brief, install a plugin with `npm install [package] --save-dev`, require it in a suitable task file, add something to the configuration file if needed, and drop it into the pipeline somewhere. Some types of plugin are particularly easy to add, for instance anything listed on the [postcss.parts](http://postcss.parts/) web site once you have [gulp-postcss](https://github.com/postcss/gulp-postcss) installed and configured in `/gulpfile.js/tasks/styles.js`.
 
 
 
@@ -111,13 +112,12 @@ A few handy tips from the [Bower documentation](https://bower.io):
 
 ## WORKING WITH SASS
 
-* This package now supports either [gulp-ruby-sass](https://github.com/sindresorhus/gulp-ruby-sass/) (which requires [the original Ruby implementation of Sass](https://github.com/sass/sass)) or [gulp-sass](https://www.npmjs.org/package/gulp-sass) (based on the newer, experimental, and faster [libsass](https://github.com/sass/libsass), now active by default). Switch `styles.compiler` in the configuration file as needed! For reference: [Sass compatibility table](https://sass-compatibility.github.io/).
+* This project now supports either [gulp-ruby-sass](https://github.com/sindresorhus/gulp-ruby-sass/) (which requires [the original Ruby implementation of Sass](https://github.com/sass/sass)) or [gulp-sass](https://www.npmjs.org/package/gulp-sass) (based on the newer and faster [libsass](https://github.com/sass/libsass), now active by default). Switch `styles.compiler` in the configuration file as needed! For reference: [Sass compatibility table](https://sass-compatibility.github.io/).
 * [Sass](http://sass-lang.com/) files can be found in `/src/scss`. Gulp will not process Sass partials beginning with `_`; these need to be explicitly imported (see `style.scss` for an example). On the other hand, if you want to output any other CSS files just drop the underscore *e.g.* `editor-style.scss`.
+* Stylesheets are post-processed with [cssnano](http://cssnano.co/), a [PostCSS](https://github.com/postcss/postcss) plugin with [Autoprefixer](https://github.com/ai/autoprefixer) baked in, eliminating the need for vendor prefixes.
+* [Sourcemaps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) are generated by [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) to make debugging stylesheets a snap. Note: all generated CSS is production-ready (*e.g.* minified and prefixed); sourcemaps only appear in the `build` directory.
 * Packages installed with Bower or npm are in the path by default so you can `@import` Sass files directly, as seen in `style.scss`.
-* The `build` folder is provisioned with regular versions of all stylesheets but `dist` only contains minified versions for production.
-* This starter kit ships with [Normalize.css](https://necolas.github.io/normalize.css/) (imported into the `src/scss` directory using `gulp setup`; you might also like to explore the use of [normalize-scss](https://github.com/JohnAlbin/normalize-scss) for your project).
-* Compass is *not* included as [Autoprefixer](https://github.com/ai/autoprefixer), a [PostCSS](https://github.com/postcss/postcss) plugin, eliminates the need for vendor prefixing (which is what most Sass frameworks focus on these days). Instead I have included [Scut](https://davidtheclark.github.io/scut/), a minimalist library of useful Sass mixins and functions for the post-vendor prefixing era. This is easily removed if you're not interested in using it.
-* [Sourcemaps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/?redirect_from_locale=tw) are generated by [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) to make debugging stylesheets a snap.
+* This starter kit ships with [Normalize.css](https://necolas.github.io/normalize.css/) (imported into the `src/scss` directory using `gulp setup`; you might also like to explore the use of [normalize-scss](https://github.com/JohnAlbin/normalize-scss) for your project) and [Scut](https://davidtheclark.github.io/scut/), a minimalist library of useful Sass mixins and functions for the post-vendor prefixing era. Both of these are easy to remove if you're not interested in them.
 
 
 
@@ -149,7 +149,7 @@ Let's say you run across a cool project like [Headroom.js](http://wicky.nillia.m
     * Create an additional script at `src/js/headroom.js` to invoke the main script:
 
 ```language-javascript
-// Invoke Headroom.js
+// Invoke Headroom.js; the outer function is is an IIFE, the inner one is a shortcut to document.ready
 ;(function($){
   $(function(){
     $("#wrap-header").headroom({ offset: 60 });

src/inc/assets.php

@@ -57,8 +57,8 @@ function voidx_enqueue_scripts() {
   if ( !empty( $script_vars ) )
     wp_localize_script( $script_handle, 'voidxVars', $script_vars );
 
-  // Script variables specific to WP AJAX Page Loader (these are separate from the main theme script variables due to the naming requirement; the object must be `PG8Data`)
-  // This appears and NOT in the conditional block (above) because these variables will be attached to the main script handle (which may be modified after the page loader block)
+  // Script variables specific to WP AJAX Page Loader (these are separate from the main theme script variables due to the naming requirement; the object *must* be `PG8Data`)
+  // This appears here and NOT in the conditional block (above) because these variables will be attached to the main script handle (which may be modified after the page loader block)
   if ( !empty( $script_vars_page_loader ) )
     wp_localize_script( $script_handle, 'PG8Data', $script_vars_page_loader );
 

src/scss/_config.scss

@@ -30,7 +30,7 @@ $_metadata: (
 , theme-author:             "Alexander Synaptic"
 , theme-author-uri:         "http://synapticism.com"
 , theme-description:        "A minimally viable theme made with the WordPress/Gulp starter kit"
-, theme-version:            "0.2.3"
+, theme-version:            "0.2.5"
 , theme-license:            "GPLv3"
 , theme-license-uri:        "http://www.gnu.org/licenses/gpl.txt"
 , theme-tags:               (light, responsive-layout, right-sidebar, starter-theme, two-columns, translation-ready, white)