feat(html-renderer): option to skip HTML tokens parsing (#74)

mistletoe/html_renderer.py

@@ -18,19 +18,30 @@ class HtmlRenderer(BaseRenderer):
 
     See mistletoe.base_renderer module for more info.
     """
-    def __init__(self, *extras, html_escape_double_quotes=False, html_escape_single_quotes=False, **kwargs):
+    def __init__(
+        self,
+        *extras,
+        html_escape_double_quotes=False,
+        html_escape_single_quotes=False,
+        process_html_tokens=True,
+        **kwargs
+    ):
         """
         Args:
             extras (list): allows subclasses to add even more custom tokens.
             html_escape_double_quotes (bool): whether to also escape double
                 quotes when HTML-escaping rendered text.
             html_escape_single_quotes (bool): whether to also escape single
                 quotes when HTML-escaping rendered text.
+            process_html_tokens (bool): whether to include HTML tokens in the
+                processing. If `False`, HTML markup will be treated as plain
+                text: e.g. input ``<br>`` will be rendered as ``&lt;br&gt;``.
             **kwargs: additional parameters to be passed to the ancestor's
                 constructor.
         """
         self._suppress_ptag_stack = [False]
-        super().__init__(*chain((HtmlBlock, HtmlSpan), extras), **kwargs)
+        final_extras = chain((HtmlBlock, HtmlSpan) if process_html_tokens else (), extras)
+        super().__init__(*final_extras, **kwargs)
         self.html_escape_double_quotes = html_escape_double_quotes
         self.html_escape_single_quotes = html_escape_single_quotes
 

test/test_html_renderer.py

@@ -1,4 +1,5 @@
 from unittest import TestCase, mock
+from mistletoe import Document
 from mistletoe.html_renderer import HtmlRenderer
 from parameterized import parameterized
 
@@ -150,6 +151,12 @@ def test_escape_html_text(self, escape_double, escape_single, expected):
                           html_escape_single_quotes=escape_single) as renderer:
             self.assertEqual(renderer.escape_html_text('" and \''), expected)
 
+    def test_unprocessed_html_tokens_escaped(self):
+        with HtmlRenderer(process_html_tokens=False) as renderer:
+            token = Document(['<div><br> as plain text</div>\n'])
+            expected = '<p>&lt;div&gt;&lt;br&gt; as plain text&lt;/div&gt;</p>\n'
+            self.assertEqual(renderer.render(token), expected)
+
 
 class TestHtmlRendererFootnotes(TestCase):
     def setUp(self):
@@ -158,13 +165,11 @@ def setUp(self):
         self.addCleanup(self.renderer.__exit__, None, None, None)
 
     def test_footnote_image(self):
-        from mistletoe import Document
         token = Document(['![alt][foo]\n', '\n', '[foo]: bar "title"\n'])
         expected = '<p><img src="bar" alt="alt" title="title" /></p>\n'
         self.assertEqual(self.renderer.render(token), expected)
 
     def test_footnote_link(self):
-        from mistletoe import Document
         token = Document(['[name][foo]\n', '\n', '[foo]: target\n'])
         expected = '<p><a href="target">name</a></p>\n' 
         self.assertEqual(self.renderer.render(token), expected)