Allow raw HTML in caption prefix (#2679)

* Allow raw HTML in caption prefix

* Add documentation note about new behavior

Author: facelessuser

docs/src/markdown/about/changelog.md

@@ -3,8 +3,10 @@
 ## 10.16
 
 -   **NEW**: Drop support for Python 3.8.
--   **NEW**: Snippets: Added `max_retries` and `backoff_retries` options to configure new retry logic for HTTP 429 errors
-    (Too Many Requests client error).
+-   **NEW**: Snippets: Added `max_retries` and `backoff_retries` options to configure new retry logic for HTTP 429
+    errors (Too Many Requests client error).
+-   **NEW**: Caption: Prefix templates are now preserved exactly as specified allowing the insertion of HTML tags if
+    desired.
 -   **FIX**: Caption: Fix issue where manual numbers in auto were not respected appropriately.
 
 ## 10.15

docs/src/markdown/extensions/blocks/plugins/caption.md

@@ -498,6 +498,32 @@ extenconfigs = {
 }
 ```
 
+Prefix templates are inserted exactly as specified, that means you can also use raw HTML. That also means you must
+HTML escape anything that needs it as well.
+
+```py
+extenconfigs = {
+    "pymdownx.blocks.caption": {
+        "types": [
+            'caption',
+            {
+                'name': 'figure-caption',
+                'prefix': 'Figure <span class="prefix-fig-num">{}</span>.'
+                'classes': 'one-class two-class'
+            },
+            {
+                'name': 'table-caption',
+                'prefix': 'Table <span class="prefix-fig-num">{}</span>.'
+            }
+        ]
+    }
+}
+```
+
+/// new | New 10.16
+Using raw HTML in prefix templates was added in 10.16.
+///
+
 ## Global Options
 
 Options        | Type       | Descriptions

pymdownx/blocks/caption.py

@@ -35,7 +35,7 @@
 RE_SEP = re.compile(r'[_-]+')
 
 
-def update_tag(el, fig_type, fig_num, template, prepend):
+def update_tag(el, fig_type, fig_num, template, prepend, md):
     """Update tag ID and caption prefix."""
 
     # Auto add an ID
@@ -47,7 +47,7 @@ def update_tag(el, fig_type, fig_num, template, prepend):
         for child in list(el) if prepend else reversed(el):
             if child.tag == 'figcaption':
                 children = list(child)
-                value = template.format(fig_num)
+                value = md.htmlStash.store(template.format(fig_num))
                 if not len(children) or children[0].tag != 'p':
                     p = etree.Element('p')
                     span = etree.SubElement(p, 'span', {'class': 'caption-prefix'})
@@ -184,7 +184,8 @@ def run(self, doc):
                     fig_type,
                     '.'.join(str(x) for x in counter[:stack + 1]),
                     self.fig_types.get(fig_type, ''),
-                    prepend
+                    prepend,
+                    self.md
                 )
 
         # Clean up attributes
@@ -314,7 +315,8 @@ def on_end(self, block):
                     self.NAME,
                     self.fig_num,
                     prefix,
-                    self.prepend
+                    self.prepend,
+                    self.md
                 )
 
 

tests/test_extensions/test_blocks/test_captions.py

@@ -1522,3 +1522,45 @@ def test_manual_prepend(self):
             """,
             True
         )
+
+
+class TestBlocksCaptionCustomPrefix(util.MdCase):
+    """Test Blocks caption cases with `auto` level."""
+
+    extension = ['pymdownx.blocks.caption']
+    extension_configs = {
+        'pymdownx.blocks.caption': {
+            'types': [
+                'caption',
+                {
+                    'name': 'figure-caption',
+                    'prefix': 'Figure <span class="caption-num">{}</span>.'
+                },
+                {
+                    'name': 'table-caption',
+                    'prefix': 'Table <span class="caption-num">{}</span>.'
+                }
+            ]
+        }
+    }
+
+    def test_custom_prefix(self):
+        """Test custom prefix."""
+
+        self.check_markdown(
+            R'''
+            A paragraph with a caption.
+            /// figure-caption
+            This is the caption.
+            ///
+            ''',
+            R'''
+            <figure id="__figure-caption_1">
+            <p>A paragraph with a caption.</p>
+            <figcaption>
+            <p><span class="caption-prefix">Figure <span class="caption-num">1</span>.</span> This is the caption.</p>
+            </figcaption>
+            </figure>
+            ''',
+            True
+        )