Add an HtmlStash section to docs

1 files changed, 19 insertions, 0 deletions

diff --git a/docs/extensions/api.md b/docs/extensions/api.md
index 4b0d851..161e886 100644
--- a/docs/extensions/api.md
+++ b/docs/extensions/api.md
@@ -554,6 +554,25 @@ def set_link_class(self, element):
 For more information about working with ElementTree see the [ElementTree
 Documentation][ElementTree].
 
+## Working with Raw HTML {: #working_with_raw_html }
+
+Occasionally an extension may need to call out to a third party library which returns a pre-made string
+of raw HTML that needs to be inserted into the document unmodified. Raw strings can be stashed for later
+retrieval using an `htmlStash` instance, rather than converting them into `ElementTree` objects. A raw string
+(which may or may not be raw HTML) passed to `self.md.htmlStash.store()` will be saved to the stash and a
+placeholder string will be returned which should be inserted into the tree instead. After the tree is
+serialized, a postprocessor will replace the placeholder with the raw string. This prevents subsequent
+processing steps from modifying the HTML data. For example,
+
+```python
+html = "<p>This is some <em>raw</em> HTML data</p>"
+el = etree.Element("div")
+el.text = self.md.htmlStash.store(html)
+```
+
+For the global `htmlStash` instance to be available from a processor, the `markdown.Markdown` instance must
+be passed to the processor from [extendMarkdown](#extendmarkdown) and will be available as `self.md.htmlStash`.
+
 ## Integrating Your Code Into Markdown {: #integrating_into_markdown }
 
 Once you have the various pieces of your extension built, you need to tell Markdown about them and ensure that they