diff options
Diffstat (limited to 'docs/extensions/api.md')
| -rw-r--r-- | docs/extensions/api.md | 19 |
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 |