diff --git a/src/theme/Mermaid.js b/src/theme/Mermaid.js
index 8764d0829a..9cc750fb9b 100644
--- a/src/theme/Mermaid.js
+++ b/src/theme/Mermaid.js
@@ -1,10 +1,10 @@
-// Copyright © 2022 Ory Corp
+// Copyright 2022 Ory Corp
 // SPDX-License-Identifier: Apache-2.0
 
 // according to https://github.com/facebook/docusaurus/issues/1258#issuecomment-594393744
 
 // use in *.mdx like:
-
+//
 // import Mermaid from '@theme/Mermaid'
 //
 // <Mermaid chart={`
@@ -12,14 +12,14 @@
 //     cr([Create Request]) --> backoffice[Backoffice Server REST]
 // `}/>
 
-import React, { useEffect, useState } from "react"
+import React, { useEffect, useState, useRef } from "react"
 import { useColorMode } from "@docusaurus/theme-common"
 import mermaid from "mermaid"
 import styles from "./mermaid.module.css"
 import cn from "classnames"
 
 mermaid.initialize({
-  startOnLoad: true,
+  startOnLoad: false,
   logLevel: "fatal",
   securityLevel: "strict",
   arrowMarkerAbsolute: false,
@@ -41,31 +41,39 @@ mermaid.initialize({
 
 const Mermaid = ({ chart }) => {
   const [zoomed, setZoomed] = useState(false)
-  const [svg, setSvg] = useState(undefined)
-  const [id] = useState(`mermaid-${Math.random().toString(36).substr(2, -1)}`)
+  const containerRef = useRef(null)
   const toggle = () => setZoomed(!zoomed)
   const { colorMode } = useColorMode()
+  const theme = colorMode === "light" ? "neutral" : "dark"
 
   useEffect(() => {
-    // https://mermaid.js.org/config/theming.html#diagram-specific-themes
-    mermaid
-      .render(
-        id,
-        `%%{init: {'theme':'${
-          colorMode === "light" ? "neutral" : "dark"
-        }'}}%%\n${chart}`,
-      )
-      .then(({ svg }) => {
-        setSvg(svg)
+    if (!containerRef.current) return
+
+    // Clear previous content
+    containerRef.current.innerHTML = ""
+
+    // Add the mermaid diagram definition with theme
+    containerRef.current.innerHTML = `<div class="mermaid">
+      %%{init: {'theme':'${theme}'}}%%
+      ${chart}
+    </div>`
+
+    // Use mermaid.run to process the diagram
+    try {
+      mermaid.run({
+        nodes: [containerRef.current.querySelector(".mermaid")],
       })
-  }, [])
+    } catch (error) {
+      console.error("Mermaid error:", error)
+    }
+  }, [chart, theme])
 
   return (
     <>
       <div
         onClick={toggle}
+        ref={containerRef}
         className={cn(styles.graph, styles.pointer)}
-        dangerouslySetInnerHTML={{ __html: svg }}
       />
       <div
         onClick={toggle}
@@ -76,7 +84,9 @@ const Mermaid = ({ chart }) => {
         <div
           onClick={(e) => e.stopPropagation()}
           className={cn(styles.backdrop, styles.graph)}
-          dangerouslySetInnerHTML={{ __html: svg }}
+          dangerouslySetInnerHTML={{
+            __html: containerRef.current?.innerHTML || "",
+          }}
         />
       </div>
     </>
diff --git a/src/theme/SelfServiceApiFlow.js b/src/theme/SelfServiceApiFlow.js
index a8f81e82a9..e4b7fd65ad 100644
--- a/src/theme/SelfServiceApiFlow.js
+++ b/src/theme/SelfServiceApiFlow.js
@@ -6,11 +6,11 @@ import Mermaid from "./Mermaid"
 
 const chart = ({
   flows = ["login", "registration", "settings", "..."],
-  interactions = ['"Log in"', '"Sign Up"', '"Update Email"', "..."],
+  interactions = ["Log in", "Sign Up", "Update Email", "..."],
   success = "Perform flow-specific action (e.g. create user, set session cookie, ...)",
 }) => {
   const components =
-    flows.length > 1 ? `<${flows.join("|")}>` : `${flows.join("|")}`
+    flows.length > 1 ? `[${flows.join("|")}]` : `${flows.join("|")}`
   return `
 sequenceDiagram
   participant B as API Client
@@ -20,7 +20,7 @@ sequenceDiagram
   K-->>K: Create and store new ${flows.join(", ")} flow
   K->>B: HTTP 200 OK with flow as application/json payload
   B-->>B: Render form using e.g. Native iOS UI Elements
-  B-->>B: User fills out forms, clicks e.g. ${interactions}
+  B-->>B: User fills out forms, clicks e.g. ${interactions.join(", ")}
   B->>K: REST POST to e.g. /self-service/${components}?flow=...>
   K-->>K: Validates and processes payload
   alt Form payload is valid
diff --git a/src/theme/SelfServiceBrowserFlow.js b/src/theme/SelfServiceBrowserFlow.js
index 2dbcf99b31..5faacd48e5 100644
--- a/src/theme/SelfServiceBrowserFlow.js
+++ b/src/theme/SelfServiceBrowserFlow.js
@@ -10,7 +10,7 @@ const chart = ({
   success = "Perform flow-specific action (e.g. create user, set session cookie, ...)",
 }) => {
   const components =
-    flows.length > 1 ? `<${flows.join("|")}>` : `${flows.join("|")}`
+    flows.length > 1 ? `[${flows.join("|")}]` : `${flows.join("|")}`
   return `
 sequenceDiagram
   participant B as Browser App
@@ -18,15 +18,15 @@ sequenceDiagram
   participant K as Ory
   B->>K: Follow link to /self-service/${components}/browser
   K-->>K: Create and store new ${flows.join(", ")} flow
-  K->>A: HTTP 302 Found <selfservice.flows.${components}.ui_url>?flow=<flow-id>
-  A-->>K: Fetches data to render forms using /selfservice/${components}/flows?id=<flow-id>
+  K->>A: HTTP 302 Found [selfservice.flows.${components}.ui_url]?flow=[flow-id]
+  A-->>K: Fetches data to render forms using /selfservice/${components}/flows?id=[flow-id]
   A->>K: Submits User data
   K-->>K: Validates and processes form payloads
   alt Form payload is valid
     K->>B: ${success}
   else Form payload invalid
     K-->>K: Update and store flow (e.g. add form validation errors)
-    K-->>A: HTTP 302 Found <selfservice.flows.${components}.ui_url>?flow=<flow-id>
+    K-->>A: HTTP 302 Found [selfservice.flows.${components}.ui_url]?flow=[flow-id]
     A-->>K: Fetches data to render form fields and errors
     A->>K: Repeat flow with input data, submit, validate, ...
   end
diff --git a/src/theme/SelfServiceSpaFlow.js b/src/theme/SelfServiceSpaFlow.js
index 08232407ff..57ce94c81c 100644
--- a/src/theme/SelfServiceSpaFlow.js
+++ b/src/theme/SelfServiceSpaFlow.js
@@ -6,11 +6,11 @@ import Mermaid from "./Mermaid"
 
 const chart = ({
   flows = ["login", "registration", "settings", "..."],
-  interactions = ['"Log in"', '"Sign Up"', '"Update Email"', "..."],
+  interactions = ["Log in", "Sign Up", "Update Email", "..."],
   success = "Perform flow-specific action (e.g. create user, set session cookie, ...)",
 }) => {
   const components =
-    flows.length > 1 ? `<${flows.join("|")}>` : `${flows.join("|")}`
+    flows.length > 1 ? `[${flows.join("|")}]` : `${flows.join("|")}`
   return `
 sequenceDiagram
   participant B as AJAX Client
@@ -20,8 +20,8 @@ sequenceDiagram
   K-->>K: Create and store new ${flows.join(", ")} flow
   K->>B: HTTP 200 OK with flow as application/json payload
   B-->>B: Render form using HTML input elements
-  B-->>B: User fills out forms, clicks e.g. ${interactions}
-  B->>K: REST POST to e.g. /self-service/${components}?flow=...>
+  B-->>B: User fills out forms, clicks e.g. ${interactions.join(", ")}
+  B->>K: REST POST to e.g. /self-service/${components}?flow=[flow-id]
   K-->>K: Validates and processes payload
   alt Form payload is valid
     K->>B: ${success}