From 5944dd851ad10f62a4ecc425dab24128e6adbbd1 Mon Sep 17 00:00:00 2001
From: Mark <mark@remarkablemark.org>
Date: Wed, 3 Jun 2020 19:45:05 -0400
Subject: [PATCH] docs(readme): document option `htmlparser2` and any risks

---
 README.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index dd9a0d43..a242442d 100644
--- a/README.md
+++ b/README.md
@@ -106,7 +106,7 @@ parse(
 
 The `replace` callback allows you to swap an element with another React element.
 
-The first argument is an object with the same output as [htmlparser2](https://github.com/fb55/htmlparser2)'s [domhandler](https://github.com/fb55/domhandler#example):
+The first argument is an object with the same output as [htmlparser2](https://github.com/fb55/htmlparser2/tree/v3.10.1)'s [domhandler](https://github.com/fb55/domhandler#example):
 
 ```js
 parse('<br>', {
@@ -224,6 +224,34 @@ parse('<br>', {
 });
 ```
 
+### htmlparser2
+
+This library passes the following options to [htmlparser2](https://github.com/fb55/htmlparser2/tree/v3.10.1) on the server-side:
+
+```js
+{
+  decodeEntities: true,
+  lowerCaseAttributeNames: false
+}
+```
+
+By passing your own options, the default library options will be **replaced** (not merged).
+
+As a result, to enable `decodeEntities` and `xmlMode`, you need to do the following:
+
+```js
+parse('<p /><p />', {
+  htmlparser2: {
+    decodeEntities: true,
+    xmlMode: true
+  }
+});
+```
+
+See [htmlparser2 options](https://github.com/fb55/htmlparser2/wiki/Parser-options).
+
+> **Warning**: By overriding htmlparser2 options, there's a chance of breaking universal rendering. Do this at your own risk.
+
 ## FAQ
 
 #### Is this library XSS safe?