Document custom image conversion

2 files changed, 54 insertions, 0 deletions

diff --git a/NEWS b/NEWS
index 21c82ca..300ee46 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,7 @@
+# 0.3.5
+
+* Add `mammoth.images.inline`, and document custom image conversion.
+
 # 0.3.4
 
 * Add the function `mammoth.extractRawText`.
diff --git a/README.md b/README.md
index ae9a3f6..6e5b7a2 100644
--- a/README.md
+++ b/README.md
@@ -172,6 +172,25 @@ var options = {
 };
 ```
 
+#### Custom image handlers
+
+By default, images are converted to `<img>` elements with the source included inline in the `src` attribute.
+This behaviour can be changed by setting the `convertImage` option to an [image converter](#image-converters) .
+
+For instance, the following would replicate the default behaviour:
+
+```javascript
+var options = {
+    convertImage: mammoth.images.inline(function(element) {
+        return element.read("base64").then(function(imageBuffer) {
+            return {
+                src: "data:" + element.contentType + ";base64," + imageBuffer
+            };
+        });
+    })
+};
+```
+
 #### Document transforms
 
 Mammoth allows a document to be transformed before it is converted.
@@ -230,6 +249,9 @@ Converts the source document to HTML.
   
   * `transformDocument`: if set,
     this function is applied to the document read from the docx file before the conversion to HTML.
+    
+  * `convertImage`: by default, images are converted to `<img>` elements with the source included inline in the `src` attribute.
+    Set this option to an [image converter](#image-converters) to override the default behaviour.
 
 * Returns a promise containing a result.
   This result has the following properties:
@@ -265,6 +287,34 @@ Each message has the following properties:
 
 * `message`: a string containing the actual message
 
+#### Image converters
+
+An inline image converter can be created by calling `mammoth.images.inline(func)`.
+This creates an inline `<img>` element for each image in the original docx.
+`func` should be a function that has one argument called `element`.
+This argument is the image element being converted,
+and has the following properties:
+
+* `read([encoding])`: read the image file with the specified encoding.
+  If no encoding is specified, a `Buffer` is returned.
+  
+* `contentType`: the content type of the image, such as `image/png`.
+
+`func` should return an object (or a promise containing an object) with a `src` property,
+which will be used as the `src` attribute on the `<img>` element.
+
+For instance, the following replicates the default image conversion:
+
+```javascript
+mammoth.images.inline(function(element) {
+    return element.read("base64").then(function(imageBuffer) {
+        return {
+            src: "data:" + element.contentType + ";base64," + imageBuffer
+        };
+    });
+})
+```
+
 ## Writing style maps
 
 A style map is made up of a number of style mappings separated by new lines.