Better error handling (#354)

Add some docs

CHANGELOG.md

@@ -1,6 +1,10 @@
 Change History
 ==============
 
+v2.21.1
+---
+* Better error handling (#354)
+
 v2.21.0
 ----
 * Add `html-webpack-plugin-alter-asset-tags` event to allow plugins to adjust the script/link tags

README.md

@@ -24,8 +24,7 @@ Migration guide from 1.x
 [Changelog](https://github.com/ampedandwired/html-webpack-plugin/blob/master/CHANGELOG.md)
 
 If you used the 1.x version please take a look at the [migration guide](https://github.com/ampedandwired/html-webpack-plugin/blob/master/migration.md)
-In case I missed something please open a pull request for it.
-See also issue [#186](https://github.com/ampedandwired/html-webpack-plugin/issues/186)
+
 
 Basic Usage
 -----------
@@ -75,7 +74,7 @@ Allowed values are as follows:
 - `title`: The title to use for the generated HTML document.
 - `filename`: The file to write the HTML to. Defaults to `index.html`.
    You can specify a subdirectory here too (eg: `assets/admin.html`).
-- `template`: Path to the template. Supports loaders e.g. `html!./index.html`.
+- `template`: Webpack require path to the template. Please see the [docs](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md) for details. 
 - `inject`: `true | 'head' | 'body' | false` Inject all assets into the given `template` or `templateContent` - When passing `true` or `'body'` all javascript resources will be placed at the bottom of the body element. `'head'` will place the scripts in the head element.
 - `favicon`: Adds the given favicon path to the output html.
 - `minify`: `{...} | false` Pass a [html-minifier](https://github.com/kangax/html-minifier#options-quick-reference) options object to minify the output.
@@ -105,6 +104,13 @@ Here's an example webpack config illustrating how to use these options:
 }
 ```
 
+FAQ
+----
+
+* [Why is my html minified?](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md)
+* [Why is my `<% ... %>` template not working?](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md)
+* [How can I use handlebars/pug/ejs as template engine](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md)
+
 Generating Multiple HTML Files
 ------------------------------
 To generate more than one HTML file, declare the plugin more than
@@ -137,8 +143,7 @@ and favicon files into the markup.
 plugins: [
   new HtmlWebpackPlugin({
     title: 'Custom template',
-    template: 'my-index.ejs', // Load a custom template (ejs by default but can be changed)
-    inject: 'body' // Inject all scripts into the body (this is the default so you can skip it)
+    template: 'my-index.ejs', // Load a custom template (ejs by default see the FAQ for details)
   })
 ]
 ```

docs/template-option.md

@@ -0,0 +1,70 @@
+# The template option
+
+## History
+
+The version 2.x which was introduced last year (Sep, 2015) changed the way the template is processed.
+Instead of forcing all users to use the [blueimp](https://github.com/blueimp/JavaScript-Templates) template engine it allowed to use any webpack loader:
+
+* [jade/pug](https://github.com/pugjs/pug-loader)
+* [ejs](https://github.com/okonet/ejs-loader)
+* [underscore](https://github.com/emaphp/underscore-template-loader)
+* [handlebars](https://github.com/pcardune/handlebars-loader)
+* [html-loader](https://github.com/webpack/html-loader)
+* ...
+
+Under the hood it is using a webpack child compilation which inherits all loaders from
+your main configuration.
+
+There are two ways to set the loader:
+
+## 1) Don't set any loader
+
+By default (if you don't specify any loader in any way) a [fallback ejs loader](https://github.com/ampedandwired/html-webpack-plugin/blob/master/lib/loader.js) kicks in.
+
+## 2) Setting a loader directly for the template
+
+```js
+new HtmlWebpackPlugin({
+  // For details on `!!` see https://webpack.github.io/docs/loaders.html#loader-order
+  template: '!!handlebars!src/index.hbs'
+})
+```
+
+## 3) Setting a loader using the `module.loaders` syntax
+
+```js
+{
+  module: {
+    loaders: [
+      {
+        test: /\.hbs$/,
+        loader: 'handlebars'
+      },
+  },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: 'src/index.hbs'
+    })
+  ]
+}
+```
+
+However this also means that in the following example webpack will use the html loader for your template.
+This will causes html minification and disables the fallback loader which allows to use `ejs` syntax:
+
+```js
+{
+  module: {
+    loaders: [
+      {
+        test: /\.html$/,
+        loader: 'html'
+      },
+  },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: 'src/index.html'
+    })
+  ]
+}
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-webpack-plugin",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "description": "Simplifies creation of HTML files to serve your webpack bundles",
   "main": "index.js",
   "files": [