Add SVG rendering via mermaid.ink API and restore SVG as default format

Copilot · codingjoe · Copilot · commit b86b6acfd271 · 2025-11-01T14:38:49.000Z
Co-authored-by: codingjoe &lt;1772890+codingjoe@users.noreply.github.com&gt;
diff --git a/docs/commands.rst b/docs/commands.rst
@@ -9,19 +9,19 @@ render_workflow_graph
 
 Render workflow graph to file::
 
-    usage: manage.py render_workflow_graph [-h] [-f {mmd,mermaid}] [-d DIRECTORY]
+    usage: manage.py render_workflow_graph [-h] [-f {svg,mmd,mermaid}] [-d DIRECTORY]
                                           [workflow [workflow ...]]
 
-    Render workflow graph to file in Mermaid format.
+    Render workflow graph to file.
 
     positional arguments:
       workflow              List of workflow to render in the form
                             app_label.workflow_name
 
     optional arguments:
       -h, --help            show this help message and exit
-      -f {mmd,mermaid}, --format {mmd,mermaid}
-                            Output file format. Default: mmd (Mermaid markdown)
+      -f {svg,mmd,mermaid}, --format {svg,mmd,mermaid}
+                            Output file format. Default: svg
       -d DIRECTORY, --directory DIRECTORY
                             Output directory. Default is current working
                             directory.
diff --git a/joeflow/management/commands/render_workflow_graph.py b/joeflow/management/commands/render_workflow_graph.py
@@ -18,9 +18,9 @@ def add_arguments(self, parser):
             "--format",
             dest="format",
             type=str,
-            choices=("mmd", "mermaid"),
-            default="mmd",
-            help="Output file format. Default: mmd (Mermaid markdown)",
+            choices=("svg", "mmd", "mermaid"),
+            default="svg",
+            help="Output file format. Default: svg",
         )
         parser.add_argument(
             "-d",
diff --git a/joeflow/mermaid_utils.py b/joeflow/mermaid_utils.py
@@ -1,5 +1,15 @@
 """Utilities for generating Mermaid diagrams."""
 from collections import defaultdict
+import urllib.parse
+import urllib.request
+import base64
+
+try:
+    from mermaid import Mermaid
+    from mermaid.graph import Graph
+    MERMAID_PKG_AVAILABLE = True
+except ImportError:
+    MERMAID_PKG_AVAILABLE = False
 
 # Color constants
 COLOR_BLACK = "#000"
@@ -24,6 +34,7 @@ class MermaidDiagram:
     def __init__(self, name="", comment=None, **kwargs):
         self.name = name
         self.comment = comment
+        self.format = "svg"  # Default format for compatibility with graphviz
         self.graph_attr = {}
         self.node_attr = {}
         self.edge_attr = {}
@@ -209,18 +220,47 @@ def pipe(self, format="svg", encoding="utf-8"):
         """
         Return the diagram in the specified format.
 
-        For Mermaid, we return the source wrapped in appropriate HTML.
-        This is meant for compatibility with the graphviz API.
+        For SVG format, renders via mermaid.ink API.
+        For other formats, returns the Mermaid source.
+        
+        This maintains compatibility with the graphviz API.
         """
         source = self.source()
+        
         if format == "svg":
-            # Return raw mermaid source - rendering happens client-side
-            return source
-        elif format == "png" or format == "pdf":
-            # For file formats, return the source as-is
-            # The management command will handle file writing
-            return source
-        return source
+            # Render to SVG using mermaid.ink API
+            try:
+                svg_content = self._render_to_svg(source)
+                return svg_content if encoding else svg_content.encode('utf-8')
+            except Exception:
+                # Fallback to source if rendering fails
+                return source if encoding else source.encode('utf-8')
+        else:
+            # For other formats, return the Mermaid source
+            return source if encoding else source.encode('utf-8')
+    
+    def _render_to_svg(self, mermaid_source):
+        """
+        Render Mermaid source to SVG using mermaid.ink API.
+        
+        Args:
+            mermaid_source: Mermaid diagram source code
+            
+        Returns:
+            SVG content as string
+        """
+        # Use mermaid.ink API to render
+        # https://mermaid.ink/svg/<base64_encoded_source>
+        encoded = base64.b64encode(mermaid_source.encode('utf-8')).decode('ascii')
+        url = f"https://mermaid.ink/svg/{encoded}"
+        
+        try:
+            with urllib.request.urlopen(url, timeout=10) as response:
+                svg_content = response.read().decode('utf-8')
+                return svg_content
+        except Exception as e:
+            # If API call fails, return a fallback SVG with error message
+            raise Exception(f"Failed to render via mermaid.ink: {e}")
 
     def render(self, filename, directory=None, format="svg", cleanup=False):
         """
@@ -229,17 +269,25 @@ def render(self, filename, directory=None, format="svg", cleanup=False):
         Args:
             filename: Base filename (without extension)
             directory: Output directory
-            format: Output format (svg, png, pdf) - for compatibility
+            format: Output format (svg or mmd)
             cleanup: Cleanup intermediate files (not used for Mermaid)
         """
         import os
 
+        # Determine file extension and content based on format
+        if format == "svg":
+            ext = "svg"
+            content = self.pipe(format="svg", encoding="utf-8")
+        else:
+            ext = "mmd"
+            content = self.source()
+
         if directory:
-            filepath = os.path.join(directory, f"{filename}.mmd")
+            filepath = os.path.join(directory, f"{filename}.{ext}")
         else:
-            filepath = f"{filename}.mmd"
+            filepath = f"{filename}.{ext}"
 
         with open(filepath, "w", encoding="utf-8") as f:
-            f.write(self.source())
+            f.write(content)
 
         return filepath
diff --git a/joeflow/models.py b/joeflow/models.py
@@ -218,9 +218,9 @@ def get_graph(cls, color="black"):
     @classmethod
     def get_graph_svg(cls):
         """
-        Return graph representation of a model workflow as Mermaid diagram.
+        Return graph representation of a model workflow as SVG.
 
-        The diagram is HTML safe and can be included in a template, e.g.:
+        The SVG is HTML safe and can be included in a template, e.g.:
 
         .. code-block:: html
 
@@ -233,14 +233,12 @@ def get_graph_svg(cls):
             </html>
 
         Returns:
-            (django.utils.safestring.SafeString): Mermaid diagram markup wrapped in HTML.
+            (django.utils.safestring.SafeString): SVG representation of the workflow.
 
         """
         graph = cls.get_graph()
-        mermaid_source = graph.pipe(encoding="utf-8")
-        # Wrap in HTML div with mermaid class for rendering
-        html = f'<div class="mermaid">\n{mermaid_source}\n</div>'
-        return SafeString(html)  # nosec
+        graph.format = "svg"
+        return SafeString(graph.pipe(encoding="utf-8"))  # nosec
 
     get_graph_svg.short_description = t("graph")
 
@@ -310,9 +308,9 @@ def get_instance_graph(self):
 
     def get_instance_graph_svg(self, output_format="svg"):
         """
-        Return graph representation of a running workflow as Mermaid diagram.
+        Return graph representation of a running workflow as SVG.
 
-        The diagram is HTML safe and can be included in a template, e.g.:
+        The SVG is HTML safe and can be included in a template, e.g.:
 
         .. code-block:: html
 
@@ -325,14 +323,12 @@ def get_instance_graph_svg(self, output_format="svg"):
             </html>
 
         Returns:
-            (django.utils.safestring.SafeString): Mermaid diagram markup wrapped in HTML.
+            (django.utils.safestring.SafeString): SVG representation of a running workflow.
 
         """
         graph = self.get_instance_graph()
-        mermaid_source = graph.pipe(encoding="utf-8")
-        # Wrap in HTML div with mermaid class for rendering
-        html = f'<div class="mermaid">\n{mermaid_source}\n</div>'
-        return SafeString(html)  # nosec
+        graph.format = output_format
+        return SafeString(graph.pipe(encoding="utf-8"))  # nosec
 
     get_instance_graph_svg.short_description = t("instance graph")
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -50,6 +50,7 @@ requires-python = ">=3.9"
 dependencies = [
   "django>=2.2",
   "django-appconf",
+  "mermaid>=0.3.2",
 ]
 
 [project.optional-dependencies]

Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,7 @@ requires-python = ">=3.9"`
`50`	`50`	`dependencies = [`
`51`	`51`	`"django>=2.2",`
`52`	`52`	`"django-appconf",`
	`53`	`+ "mermaid>=0.3.2",`
`53`	`54`	`]`
`54`	`55`
`55`	`56`	`[project.optional-dependencies]`