allow users to feed mermaid diagrams into html-macros

Provide support to allow a user to configure this extension to wrap raw
Mermaid diagrams into an HTML macro block, instead of forcing to use
either `png` or `svg` formats.

This is only support for Confluence instances that support an HTML
macro.

Signed-off-by: James Knight <[email protected]>

Author: jdknight

sphinxcontrib/confluencebuilder/__init__.py

@@ -244,6 +244,10 @@ def setup(app):
     # Remove a detected title from generated documents.
     cm.add_conf_bool('confluence_remove_title', 'confluence')
 
+    # (configuration - third-party related)
+    # Wrap Mermaid nodes into HTML macros.
+    cm.add_conf_bool('confluence_mermaid_html_macro', 'confluence')
+
     # (configuration - undocumented)
     # Enablement for bulk archiving of packages (for premium environments).
     cm.add_conf_bool('confluence_adv_bulk_archiving')

sphinxcontrib/confluencebuilder/transmute/ext_sphinxcontrib_mermaid.py

@@ -4,6 +4,7 @@
 from docutils import nodes
 from sphinxcontrib.confluencebuilder.compat import docutils_findall as findall
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger
+from sphinxcontrib.confluencebuilder.nodes import confluence_html
 
 # ##############################################################################
 # disable import/except warnings for third-party modules
@@ -50,12 +51,20 @@ def __init__(self, builder):
             self.builder = builder
     mock_translator = MockTranslator(builder)
 
+    # if a user configures to use a mermaid/html-macro hint, we will
+    # instead leave the raw content as is and wrap things in an HTML macro
+    format_ = builder.config.mermaid_output_format
+    if not builder.config.confluence_mermaid_html_macro and format_ == 'raw':
+        format_ = 'png'
+
     for node in findall(doctree, mermaid):
-        try:
-            format_ = builder.config.mermaid_output_format
-            if format_ == 'raw':
-                format_ = 'png'
+        if format_ == 'raw':
+            raw_html = f'<div class="mermaid">{node["code"]}</div>'
+            new_node = confluence_html(rawsource=raw_html)
+            node.replace_self(new_node)
+            continue
 
+        try:
             fname, _ = mermaid_render(mock_translator,
                 node['code'], node['options'], format_, 'mermaid')
             if not fname: