diff --git a/README.md b/README.md index 234e168d..3ee2b7b7 100644 --- a/README.md +++ b/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 `

1. Hello world

` 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.