Merge branch 'release/v0.8.0' into develop

Author: eKoopmans

README.md

@@ -2,32 +2,27 @@
 
 html2pdf converts any webpage or element into a printable PDF entirely client-side using [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF).
 
-## Install
+## Getting started
 
-1. Copy `html2pdf.js` to your project directory.
-2. Fetch the dependencies `html2canvas` and `jsPDF`, which can be found in the `vendor` folder.
-3. Include the files in your HTML document (**order is important**, otherwise `jsPDF` will override `html2canvas` with its own internal implementation):
+There are two ways to install html2pdf:
 
-```html
-<script src="jspdf.min.js"></script>
-<script src="html2canvas.min.js"></script>
-<script src="html2pdf.js"></script>
-```
-
-**Note:** For best results, use the custom build of `html2canvas` found in the `vendor` folder, which contains added features and hotfixes.
+1. **NPM:** Use `npm install --save html2pdf` to add html2pdf and its dependencies to your project.
+2. **HTML:** Download `dist/html2pdf.bundle.min.js` to your project folder and include it in your HTML with: `<script src="html2pdf.bundle.min.js"></script>`.
 
-## Usage
-
-### Basic usage
-
-Including html2pdf exposes the `html2pdf` function. Calling it will create a PDF and prompt the user to save the file:
+Once installed, html2pdf is ready to use. This command will generate a PDF of `#element-to-print` and prompt the user to save the result:
 
 ```js
 var element = document.getElementById('element-to-print');
 html2pdf(element);
 ```
 
-The PDF can be configured using an optional `opt` parameter:
+*Note: html2pdf **will not run in Node.js**, it must be run in a browser.*
+
+*[Click here](#dependencies) for more information about using the unbundled version `dist/html2canvas.min.js`.*
+
+## Options
+
+html2pdf can be configured using an optional `opt` parameter:
 
 ```js
 var element = document.getElementById('element-to-print');
@@ -42,18 +37,16 @@ html2pdf(element, {
 
 The `opt` parameter has the following optional fields:
 
-|Name        |Type            |Default                       |Description                                                                                  |
-|------------|----------------|------------------------------|---------------------------------------------------------------------------------------------|
-|margin      |number or array |0                             |PDF margin. Array can be either [vMargin, hMargin] or [top, left, bottom, right].            |
-|filename    |string          |'file.pdf'                    |The default filename of the exported PDF.                                                    |
-|image       |object          |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below.   |
-|enableLinks |boolean         |true                          |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags.                 |
+|Name        |Type            |Default                       |Description                                                                                                 |
+|------------|----------------|------------------------------|------------------------------------------------------------------------------------------------------------|
+|margin      |number or array |0                             |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
+|filename    |string          |'file.pdf'                    |The default filename of the exported PDF.                                                                   |
+|image       |object          |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below.                  |
+|enableLinks |boolean         |true                          |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags.                                |
 |html2canvas |object          |{ }                           |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/documentation.html#available-options) for usage).|
 |jsPDF       |object          |{ }                           |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
 
-### Extra features
-
-#### Page-breaks
+### Page-breaks
 
 You may add `html2pdf`-specific page-breaks to your document by adding the CSS class `html2pdf__page-break` to any element (normally an empty `div`). For React elements, use `className=html2pdf__page-break`. During PDF creation, these elements will be given a height calculated to fill the remainder of the PDF page that they are on. Example usage:
 
@@ -65,7 +58,7 @@ You may add `html2pdf`-specific page-breaks to your document by adding the CSS c
 </div>
 ```
 
-#### Image type and quality
+### Image type and quality
 
 You may customize the image type and quality exported from the canvas by setting the `image` option. This must be an object with the following fields:
 
@@ -78,9 +71,17 @@ These options are limited to the available settings for [HTMLCanvasElement.toDat
 
 ## Dependencies
 
-html2pdf depends on the external packages [`html2canvas`](https://github.com/niklasvh/html2canvas) and [`jsPDF`](https://github.com/MrRio/jsPDF).
+html2pdf depends on the external packages [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF). These dependencies are automatically loaded when using NPM or the bundled package.
+
+If using the unbundled `dist/html2pdf.min.js` (or its un-minified version), you must also include each dependency. Order is important, otherwise html2canvas will be overridden by jsPDF's own internal implementation:
+
+```html
+<script src="jspdf.min.js"></script>
+<script src="html2canvas.min.js"></script>
+<script src="html2pdf.min.js"></script>
+```
 
-For best results, use [this custom build](https://github.com/eKoopmans/html2canvas/tree/develop) of `html2canvas`, which includes bugfixes and adds support for box-shadows and custom resolutions (via the `dpi`/`scale` options).
+html2pdf currently uses [this fork](https://github.com/eKoopmans/html2canvas/tree/develop) of html2canvas to resolve a few bugs and add support for box-shadows and custom resolutions (via the `dpi`/`scale` options).
 
 ## Contributing
 
@@ -90,7 +91,7 @@ When submitting an issue, please provide reproducible code that highlights the i
 
 ### Pull requests
 
-Right now, html2pdf is a single source file located in `/src/`. If you want to create a new feature or bugfix, feel free to fork and submit a pull request!
+If you want to create a new feature or bugfix, please feel free to fork and submit a pull request! Use the [`develop`](/eKoopmans/html2pdf/tree/develop) branch, which features the latest development, and make changes to `/src/` rather than directly to `/dist/`. You can test your changes by rebuilding with `npm run build`.
 
 ## Credits