From 49e1d29d791926229e2bbafd8132666d74d14883 Mon Sep 17 00:00:00 2001 From: Cris Luengo Date: Thu, 28 Jan 2021 12:12:06 -0700 Subject: Add an HtmlStash section to docs --- docs/extensions/api.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) 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 = "

This is some raw HTML data

" +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 -- cgit v1.2.1