From 5ddab207f1d3ff5de4cf39c4158369b2bc6c5eb2 Mon Sep 17 00:00:00 2001
From: KillyMXI <killy.mxi@gmail.com>
Date: Wed, 14 Dec 2022 17:58:34 +0400
Subject: [PATCH] document the usage of metadata object and add a note about
 batch performance

---
 packages/html-to-text/README.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/html-to-text/README.md b/packages/html-to-text/README.md
index 7e8c7a4..d874f77 100644
--- a/packages/html-to-text/README.md
+++ b/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).