diff --git a/README.md b/README.md
index 9cb6380..0a65148 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,13 @@ Install the plugin with npm:
$ npm install html-webpack-plugin@2 --save-dev
```
+Migration guide from 1.x
+------------------------
+
+Please see the 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
-----------
diff --git a/migration.md b/migration.md
new file mode 100644
index 0000000..b8535f6
--- /dev/null
+++ b/migration.md
@@ -0,0 +1,157 @@
+# Migrating from 1.x to 2.x
+
+## Default config
+
+https://github.com/ampedandwired/html-webpack-plugin/tree/master/examples/default
+
+As of 2.x the `inject` options is set to true by default which means that all your javascript, css files and manifest files are injected automatically. See https://github.com/ampedandwired/html-webpack-plugin#configuration
+
+The default template has changed according to the inject option - but should behave like the previous version did.
+
+
+```js
+var HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+ // ...
+ plugins: [
+ new HtmlWebpackPlugin()
+ ]
+};
+```
+
+## Custom template
+
+This inject feature aims to simpify your custom templates:
+https://github.com/ampedandwired/html-webpack-plugin/tree/master/examples/custom-template
+
+```js
+var HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+ // ...
+ plugins: [
+ new HtmlWebpackPlugin({
+ template: 'template.html'
+ })
+ ]
+};
+```
+
+```html
+
+
+
+
+ Webpack App
+
+
+
+
+```
+
+Although we did not specify any script tags or link tags they will be injected automatically and the result will be:
+```html
+
+
+
+
+ Webpack App
+
+
+
+
+
+
+```
+
+## Tempalting and variables
+
+As of 2.x blueimp was replaced by lodash/underscore/ejs templates as they are more common.
+This also removes the `o` in template variables. ` ` becomes `` it also allows to escape variables by using `<%-` instead of `<%=` to prevent unexpected behaviours: ``
+
+# Loaders in templates
+Loaders may now be used inside the template the same way as you would expect in your javascript files.
+For the following example you would have to configure a html and url/file-loader:
+
+```html
+
+<%= require('partial.html'); %>
+```
+
+## Custom template engines
+
+Maybe you prefer jade or blueimp over underscore - or your project is using jade for the front end part.
+With 2.x you can use the webpack loaders either once only for the template as in the following example.
+where we use jade (requires the [jade-loader](https://github.com/webpack/jade-loader)):
+
+```js
+var HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+ // ...
+ plugins: [
+ new HtmlWebpackPlugin({
+ template: 'jade!template.jade'
+ })
+ ]
+};
+```
+
+or by configuring webpack to handle all `.jade` files:
+
+```js
+module.exports = {
+ // ...
+ module: {
+ loaders: [
+ { test: /\.jade$/, loader: 'jade' }
+ ]
+ },
+ plugins: [
+ new HtmlWebpackPlugin({
+ template: 'template.jade'
+ })
+ ]
+};
+```
+
+Please note that if you specify the loader and use 'jade!template.jadde' webpack will try to apply the jade loader twice and fail.
+
+## Isomorph apps
+
+As of the loader changes in 2.x the `templateContent` was removed.
+However you can still use custom javascript functions to generate a template:
+
+```js
+module.exports = {
+ // ...
+ plugins: [
+ new HtmlWebpackPlugin({
+ template: 'template.js'
+ })
+ ]
+};
+```
+Simple template.js
+```js
+module.exports = '...';
+```
+More advanced template.js
+```js
+ module.exports = function(compilationResult, chunks, assets, compilation) {
+ return '..';
+ };
+```
+Using loaders inside a template.js
+```js
+ // This function has to return a string or promised string:
+ module.exports = function(compilationResult, chunks, assets, compilation) {
+ // Play around with the arguments and then use the webpack jade loader to load the jade:
+ return require('./template.jade')({assets: assets});
+ };
+```
+
+Unfortunately `__dirname` does not work correctly.
+If someone know why I would love to merge a pull request.
+A good start point might be here: https://github.com/webpack/webpack/issues/135
\ No newline at end of file