Document escape method

README.md

@@ -208,6 +208,18 @@ Turndown iterates over the set of rules, and picks the first one that matches th
 
 The plugin API provides a convenient way for developers to apply multiple extensions. A plugin is just a function that is called with the `TurndownService` instance.
 
+## Escaping Markdown Characters
+
+Turndown uses backslashes (`\`) to escape Markdown characters in the HTML input. This ensures that these characters are not interpreted as Markdown when the output is compiled back to HTML. For example, the contents of `<h1>1. Hello world</h1>` needs to be escaped to `1\. Hello world`, otherwise it will be interpreted as a list item rather than a heading.
+
+To avoid the complexity and the performance implications of parsing the content of every HTML element as Markdown, Turndown uses a group of regular expressions to escape potential Markdown syntax. As a result, the escaping rules can be quite aggressive.
+
+### Overriding `TurndownService.prototype.escape`
+
+If you are confident in doing so, you may want to customise the escaping behaviour to suit your needs. This can be done by overriding `TurndownService.prototype.escape`. `escape` takes the text of each HTML element and should return a version with the Markdown characters escaped.
+
+Note: text in code elements is never passed to`escape`.
+
 ## License
 
 turndown is copyright © 2017+ Dom Christie and released under the MIT license.