diff --git a/nicegui/elements/markdown.js b/nicegui/elements/markdown.js
index ad9f54eded..3d7572eb13 100644
--- a/nicegui/elements/markdown.js
+++ b/nicegui/elements/markdown.js
@@ -7,7 +7,8 @@ export default {
     await loadResource(window.path_prefix + this.codehilite_css_url);
     if (this.use_mermaid) {
       this.mermaid = (await import("mermaid")).default;
-      this.renderMermaid();
+      await this.mermaid.initialize({ startOnLoad: false });
+      await this.renderMermaid();
     }
   },
   data() {
@@ -16,13 +17,20 @@ export default {
     };
   },
   updated() {
-    this.renderMermaid();
+    if (this.mermaid) {
+      this.renderMermaid();
+    }
   },
   methods: {
-    renderMermaid() {
-      this.$el.querySelectorAll(".mermaid-pre").forEach(async (pre, i) => {
-        await this.mermaid.run({ nodes: [pre.children[0]] });
-      });
+    async renderMermaid() {
+      const elements = this.$el.querySelectorAll(".mermaid-pre");
+      for (const pre of elements) {
+        try {
+          await this.mermaid.run({ nodes: [pre.children[0]] });
+        } catch (error) {
+          console.error('Failed to render mermaid diagram:', error);
+        }
+      }
     },
   },
   props: {
diff --git a/nicegui/elements/markdown.py b/nicegui/elements/markdown.py
index 76177b036f..144081b867 100644
--- a/nicegui/elements/markdown.py
+++ b/nicegui/elements/markdown.py
@@ -1,7 +1,6 @@
 import os
 from functools import lru_cache
 from typing import List
-
 import markdown2
 from fastapi.responses import PlainTextResponse
 from pygments.formatters import HtmlFormatter  # pylint: disable=no-name-in-module
@@ -18,14 +17,14 @@ class Markdown(ContentElement, component='markdown.js', default_classes='nicegui
 
     def __init__(self,
                  content: str = '', *,
-                 extras: List[str] = ['fenced-code-blocks', 'tables'],  # noqa: B006
+                 extras: List[str] = ['fenced-code-blocks', 'tables', 'mermaid'],  # noqa: B006
                  ) -> None:
         """Markdown Element
 
         Renders Markdown onto the page.
 
         :param content: the Markdown content to be displayed
-        :param extras: list of `markdown2 extensions <https://github.com/trentm/python-markdown2/wiki/Extras#implemented-extras>`_ (default: `['fenced-code-blocks', 'tables']`)
+        :param extras: list of `markdown2 extensions <https://github.com/trentm/python-markdown2/wiki/Extras#implemented-extras>`_ (default: `['fenced-code-blocks', 'tables', 'mermaid']`)
         """
         self.extras = extras[:]
         super().__init__(content=content)
diff --git a/website/documentation/content/markdown_documentation.py b/website/documentation/content/markdown_documentation.py
index 28d7532bb7..a760792fb7 100644
--- a/website/documentation/content/markdown_documentation.py
+++ b/website/documentation/content/markdown_documentation.py
@@ -67,6 +67,49 @@ def markdown_latex():
     ''', extras=['latex'])
 
 
+@doc.demo('Markdown with Mermaid diagrams', '''
+    You can create diagrams using Mermaid syntax.
+    Mermaid support is enabled by default.
+    See the [Mermaid documentation](https://mermaid.js.org/) for all available diagram types.
+''')
+def markdown_mermaid():
+    ui.markdown('''
+        ```mermaid
+        graph TD
+            A[Start] --> B{Is it working?}
+            B -- Yes --> C[Great!]
+            B -- No --> D[Debug]
+            D --> B
+        ```
+
+        **NiceGUI communication**
+
+        ```mermaid
+        sequenceDiagram
+            participant Client as Browser/Client
+            participant Server as NiceGUI Server
+            participant Backend as Python Backend
+            
+            Client->>Server: HTTP: Initial page request
+            Server-->>Client: HTML + JavaScript
+            
+            Note over Client,Server: WebSocket Connection
+            Client->>Server: WS: Connect
+            Server-->>Client: WS: Connection established
+            
+            Note over Client,Backend: Real-time Updates
+            Client->>Server: WS: UI Event (e.g., button click)
+            Server->>Backend: Execute Python callback
+            Backend->>Server: Update UI state
+            Server-->>Client: WS: UI updates
+            
+            Note over Client,Server: Auto-refresh
+            Server->>Client: WS: Push updates (if page changes)
+            Client->>Client: Update UI automatically
+        ```
+    ''')
+
+
 @doc.demo('Change Markdown content', '''
     You can change the content of a Markdown element by setting its `content` property or calling `set_content`.
 ''')