turndown 4.0.2 → 6.0.0

package/README.md

@@ -40,7 +40,11 @@ var markdown = turndownService.turndown(document.getElementById('content'))
 
 ## Options
 
-Options can be passed in to the constructor on instantiation.
+Options can be passed in to the constructor on instantiation. For example:
+
+```js
+var turndownService = new TurndownService({ option: 'value' })
+```
 
 | Option                | Valid values  | Default |
 | :-------------------- | :------------ | :------ |
@@ -195,7 +199,7 @@ rules.emphasis = {
 
 ### Rule Precedence
 
-Turndown iterates over the set of rules, and picks the first one that matches satifies the `filter`. The following list describes the order of precedence:
+Turndown iterates over the set of rules, and picks the first one that matches the `filter`. The following list describes the order of precedence:
 
 1. Blank rule
 2. Added rules (optional)
@@ -208,6 +212,18 @@ Turndown iterates over the set of rules, and picks the first one that matches sa
 
 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.