include migrations section in readme and generate new readme document…

…ation

.verbrc.md

@@ -38,6 +38,9 @@ Versions of `grunt-assemble` at and above `0.2.0` contain the code from the orig
 ### Usage Examples
 {%= docs("examples") %}
 
+### Migrations
+{%= docs("v6-diffs") %}
+
 ## Contributing
 {%= include("contributing") %}
 

README.md

@@ -95,6 +95,12 @@ Default: `undefined`
 
 The directory to use as the "cwd" for [layouts](http://assemble.io/docs/options-layout.html). When this option is defined, layouts may be defined using only the name of the layout.
 
+### [layouts](http://assemble.io/docs/options-layouts.html)
+Type: `String|Array<String>`
+Default: `undefined`
+
+A glob pattern to be used to find layouts. When this option is defined, the `layoutdir` option is ignored and layouts specified in templates will be searched for using the specified glob pattern(s).
+
 ### [layout](http://assemble.io/docs/options-layout.html)
 Type: `String`
 Default: `undefined`
@@ -220,6 +226,77 @@ assemble: {
 
 Visit [Assemble's documentation](http://assemble.io) for many more examples and pointers on getting started.
 
+### Migrations
+
+#### Breaking changes between versions `0.5.0` and `0.6.0`
+
+Version 6 is using [assemble-handlebars][] version `0.4.0` which updates [handlebars-helpers][] to version `0.6.0`. Due to this update, there are some breaking changes with how some helpers are loaded and some missing/added helpers.
+
+The following list contains the breaking changes that we have noticed that may require updates to existing templates.
+
+**helpers loaded from package.json**
+
+Any helpers declared in `dependencies` or `devDependencies` and have their name in the `keywords` property will no longer be loaded automatically. To load the helpers, just include the package name in the `helpers` option for your `grunt-assemble` target:
+
+```js
+assemble: {
+  options: {
+    helpers: ['handlebars-helper-eachitems']
+  }
+}
+```
+
+**new path helpers**
+
+Helpers have been added that map to methods on the built-in `path` module. Some of these helpers are also properties that `grunt-assemble` adds automatically to `page` properties. To use the page property, use the `this` keyword before the property name. To use the helper, use it like any other helper.
+
+```handlebars
+{{this.basename}}
+{{basename this.path}}
+```
+
+**missing helper "inspect"**
+
+The "inspect" helper has been removed from `handlebars-helpers`. The test fixtures in this project use the "inspect" helper so it has been recreated [here](./test/helpers/logging.js).
+
+**missing helper "unless_eq"**
+
+The "unless_eq" helper has been renamed to "unlessEq".
+
+**missing helper "md" or "markdown"**
+
+There is a bug in `handlebars-helpers@0.6` that causes the `md` and `markdown` helpers to not be registered correctly. This has been fixed in newer versions of `handlebars-helpers`, however those changes have made it here yet. There is currently a refactor of `grunt-assemble` that will include the fix, but for now, the following is a work-around:
+
+Create a file and register the helpers manually:
+
+```js
+// helpers/markdown.js
+module.exports.register = function (Handlebars) {
+  'use strict';
+
+  Handlebars.registerHelper('markdown', require('helper-markdown')());
+  Handlebars.registerHelper('md', require('helper-md').sync);
+};
+```
+
+```js
+// Gruntfile.js
+assemble: {
+  options: {
+    helpers: ['./helpers/*.js']
+  }
+}
+```
+
+**handlebars 4 changed how context depths are handled**
+
+`assemble-handlebars` is also using a newer version of handlebars that changed how the depth context is handled. Some of the block helpers that would create a new depth, no longer create the depth. This requires changing some templates that use the `{{../}}` syntax to reduce the amount of `../` segments used. This can be seen in block helpers that don't modify the context, like `{{#if}}{{/if}}` and `{{#is}}{{/is}}`.
+
+
+[assemble-handlebars]: https://github.com/assemble/assemble-handlebars
+[handlebars-helpers]: https://github.com/assemble/handlebars-helpers
+
+
 ## Contributing
 In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality, and please re-build the documentation with [grunt-verb](https://github.com/assemble/grunt-verb) before submitting a pull request.
 
@@ -320,9 +397,9 @@ Visit [assemble.io/assemble-middleware](http:/assemble.io/assemble-middleware/)
 * 2013-03-18   v0.3.14       new relative helper for resolving relative paths                           
 
 ## License
-Copyright (c) 2015 Jon Schlinkert, Brian Woodward, contributors.  
+Copyright (c) 2017 Jon Schlinkert, Brian Woodward, contributors.  
 Released under the MIT license
 
 ***
 
-_This file was generated by [grunt-verb](https://github.com/assemble/grunt-verb) on March 16, 2015._
+_This file was generated by [grunt-verb](https://github.com/assemble/grunt-verb) on March 15, 2017._

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "grunt-assemble",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "main": [
     "./lib/assemble"
   ]

docs/v6-diffs.md

@@ -1,4 +1,5 @@
-## Breaking changes between versions 5 and 6
+
+### Breaking changes between versions `0.5.0` and `0.6.0`
 
 Version 6 is using [assemble-handlebars][] version `0.4.0` which updates [handlebars-helpers][] to version `0.6.0`. Due to this update, there are some breaking changes with how some helpers are loaded and some missing/added helpers.
 
@@ -64,3 +65,7 @@ assemble: {
 **handlebars 4 changed how context depths are handled**
 
 `assemble-handlebars` is also using a newer version of handlebars that changed how the depth context is handled. Some of the block helpers that would create a new depth, no longer create the depth. This requires changing some templates that use the `{{../}}` syntax to reduce the amount of `../` segments used. This can be seen in block helpers that don't modify the context, like `{{#if}}{{/if}}` and `{{#is}}{{/is}}`.
+
+
+[assemble-handlebars]: https://github.com/assemble/assemble-handlebars
+[handlebars-helpers]: https://github.com/assemble/handlebars-helpers