document the usage of metadata object

and add a note about batch performance

packages/html-to-text/README.md

@@ -50,7 +50,7 @@ const text = convert(html, {
 console.log(text); // Hello World
 ```
 
-Configure `html-to-text` once for batch processing:
+Configure `html-to-text` once for batch processing (recommended for good performance):
 
 ```js
 const { compile } = require('html-to-text');
@@ -291,6 +291,25 @@ Refer to [generic formatters](https://github.com/html-to-text/node-html-to-text/
 
 Refer to [BlockTextBuilder](https://github.com/html-to-text/node-html-to-text/blob/master/packages/base/src/block-text-builder.js) for available functions and arguments.
 
+#### Custom metadata
+
+If you need to supply extra information about your HTML documents to use in custom formatters - it can be done with the help of metadata object.
+
+It is supplied as an extra argument to the convert function:
+
+```javascript
+import { compile, convert } from 'html-to-text';
+
+// for batch use:
+const compiledConvert = compile(options);
+let text = compiledConvert(html, metadata);
+
+// for single use:
+let text = convert(html, options, metadata);
+```
+
+And it can be accessed within formatter functions as `builder.metadata`.
+
 #### Call other formatters from a custom formatter
 
 Most of the times this is *not* what you actually need. Most practical problems can be solved with [selectors](#selectors).