Merge pull request #1037 from sphinx-contrib/support-html-macros-for-mermaid

Allow users to feed mermaid diagrams into html-macros

Author: jdknight

doc/configuration.rst

@@ -2174,6 +2174,54 @@ Advanced processing configuration
     - |confluence_disable_autogen_title|_
     - |confluence_title_overrides|_
 
+Third-party related options
+---------------------------
+
+.. note::
+
+    The configurations in this section are specific to supporting
+    :ref:`third-party extensions <extensions_third_party>`; results may
+    vary.
+
+.. confval:: confluence_mermaid_html_macro
+
+    .. versionadded:: 2.7
+
+    .. warning::
+
+        This option relies on an HTML macro which is not available in a
+        default  Confluence configuration. Using this option is only useful
+        for users that have instances where a system administrator has
+        enabled their use.
+
+    .. note::
+
+        This option will most likely require additional configuration to
+        function. Setting this option only produces HTML macros with Mermaid
+        content but does not automatically include the JavaScript required to
+        process this content.
+
+        There can be various ways an instance/page can be configured to
+        include Mermaid JS support. For example, adding the following content
+        on the page planning to render diagrams:
+
+        .. code-block:: rst
+
+            .. confluence_html::
+
+                <script type="module">
+                import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+                </script>
+
+    When using the `sphinxcontrib-mermaid`_ extension, this option can be
+    used pass raw Mermaid figures into an HTML macro.
+
+    .. code-block:: python
+
+        confluence_mermaid_html_macro = True
+
+    See also |confluence_html_macro|_.
+
 Other options
 -------------
 
@@ -2281,6 +2329,7 @@ Deprecated options
 .. _root_doc: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-root_doc
 .. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
 .. _sphinx.ext.imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
+.. _sphinxcontrib-mermaid: https://pypi.org/project/sphinxcontrib-mermaid/
 .. _suppress_warnings: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings
 .. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
 .. _write_doc: https://www.sphinx-doc.org/en/master/extdev/builderapi.html#sphinx.builders.Builder.write_doc

doc/features.rst

@@ -194,6 +194,8 @@ Type                              Notes
 
     \newpage
 
+.. _extensions_third_party:
+
 Extensions (Third-party)
 ------------------------
 
@@ -277,7 +279,9 @@ Type                              Notes
 `sphinxcontrib-kroki`_            Supported
 `sphinxcontrib-mermaid`_          Limited support.
 
-                                  Requires a PNG/SVG configuration.
+                                  Requires a PNG/SVG configuration. Raw/HTML
+                                  renders can be used for environments with
+                                  HTML macro support.
 `sphinxcontrib-nwdiag`_           Limited support.
 
                                   PNGs only; cannot configure for SVG at this

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: