From bc297e5e496d9f48ef77581b7fb41fdf328a62cf Mon Sep 17 00:00:00 2001
From: kj_sh604
Date: Sun, 15 Mar 2026 16:19:35 -0400
Subject: refactor: dev-docs/

---
 .../docs/@excalidraw/mermaid-to-excalidraw/api.mdx | 155 +++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 dev-docs/docs/@excalidraw/mermaid-to-excalidraw/api.mdx

(limited to 'dev-docs/docs/@excalidraw/mermaid-to-excalidraw/api.mdx')

diff --git a/dev-docs/docs/@excalidraw/mermaid-to-excalidraw/api.mdx b/dev-docs/docs/@excalidraw/mermaid-to-excalidraw/api.mdx
new file mode 100644
index 0000000..f3212b4
--- /dev/null
+++ b/dev-docs/docs/@excalidraw/mermaid-to-excalidraw/api.mdx
@@ -0,0 +1,155 @@
+# API
+
+At the moment the mermaid-to-excalidraw works in two steps. First, you call `parseMermaidToExcalidraw(mermaidSyntax)` on the mermaid diagram definition string, which resolves with elements in a skeleton format — a simplified excalidraw JSON format (docs coming soon). You then pass them to `convertToExcalidrawElements(elements)` to get the fully qualified excalidraw elements you can render in the editor.
+
+The need for these two steps is due to the [@excalidraw/excalidraw](/docs/@excalidraw/excalidraw/installation) being a **UMD** build so we currently cannot import the `convertToExcalidrawElements()` util alone, until we support a tree-shakeable **ESM** build.
+
+## parseMermaidToExcalidraw
+
+This API receives the mermaid syntax as the input, and resolves to skeleton Excalidraw elements. You will need to call `convertToExcalidraw` API to convert them to fully qualified elements that you can render in Excalidraw.
+
+** Example **
+
+```ts
+import { parseMermaidToExcalidraw } from "@excalidraw/mermaid-to-excalidraw";
+import { convertToExcalidrawElements}  from "@excalidraw/excalidraw"
+try {
+  const { elements, files } = await parseMermaidToExcalidraw(mermaidSyntax: string, {
+    fontSize: number,
+  });
+  const excalidrawElements = convertToExcalidrawElements(elements);
+  // Render elements and files on Excalidraw
+} catch (e) {
+  // Parse error, displaying error message to users
+}
+```
+
+## Supported Diagram Types
+
+Currently only [flowcharts](https://mermaid.js.org/syntax/flowchart.html) are supported. Oother diagram types will be rendered as an image in Excalidraw.
+
+### Flowchart
+
+#### Excalidraw Regular Shapes
+
+**Rectangles**, **Circle**, **Diamond**, and **Arrows** are fully supported in Excalidraw
+
+```
+flowchart TD
+  A[Christmas] -->|Get money| B(Go shopping)
+  B --> C{Let me think}
+  C -->|One| D[Laptop]
+  C -->|Two| E[iPhone]
+  C -->|Three| F[Car]
+ ```
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/c8ea84fc-e9fb-4652-9a12-154136d1a798"  width="250" height="200"/>
+
+
+```
+flowchart LR
+  id1((Hello from Circle))
+```
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/6202a8b9-8aa7-451e-9478-4d8d75c0f2fa"  width="250" height="200"/>
+
+
+#### Subgraphs
+
+Subgraphs are grouped diagrams hence they are also supported in Excalidraw
+
+```
+flowchart TB
+  c1-->a2
+  subgraph one
+  a1-->a2
+  end
+  subgraph two
+  b1-->b2
+  end
+  subgraph three
+  c1-->c2
+  end
+```
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/098bce52-8f93-437c-9a06-c6972e27c70a"  width="350" height="200"/>
+
+#### Unsupported shapes fallback to Rectangle
+
+**Subroutine**, **Cylindrical**, **Asymmetric**, **Hexagon**, **Parallelogram**, **Trapezoid** are not supported in Excalidraw hence they fallback to the closest shape **Rectangle**
+
+```
+flowchart LR
+  id1[[Subroutine fallback to Rectangle]]
+  id2[(Cylindrical fallback to Rectangle)]
+  id3>Asymmetric fallback to Rectangle]
+  id4{{Hexagon fallback to Rectangle}}
+  id5[/Parallelogram fallback to Rectangle /]
+  id6[/Trapezoid fallback to Rectangle\]
+```
+The above shapes are not supported in Excalidraw hence they fallback to Rectangle
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/cb269473-16c5-4c35-bd7a-d631d8cc5b47"  width="350" height="200"/>
+
+#### Markdown fallback to Regular text
+
+Since we don't support wysiwyg text editor yet, hence [Markdown Strings](https://mermaid.js.org/syntax/flowchart.html#markdown-strings) will fallback to regular text.
+
+```
+flowchart LR
+  A("`Hello **World**`") --> B("`Whats **up** ?`")
+```
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/107bd428-9ab9-42d4-ba12-b1e29c8db478"  width="250" height="200"/>
+
+#### Basic FontAwesome fallback to text
+
+The [FontAwesome](https://mermaid.js.org/syntax/flowchart.html#basic-support-for-fontawesome) icons aren't support so they won't be rendered in Excalidraw
+
+```
+flowchart TD
+  B["fab:fa-twitter for peace"]
+  B-->C[fa:fa-ban forbidden]
+  B-->E(A fa:fa-camera-retro perhaps?)
+```
+
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/7a693863-c3f9-42ff-b325-4b3f8303c7af"  width="250" height="200"/>
+
+#### Cross Arrow head fallback to Bar Arrow head
+
+```
+flowchart LR
+  Start x--x Stop
+```
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/217dd1ad-7f4e-4c80-8c1c-03647b42d821"  width="250" height="200"/>
+
+
+## Unsupported Diagram Types
+
+Currently only [flowcharts](https://mermaid.js.org/syntax/flowchart.html) are supported. All other diagram types will be rendered as an image in Excalidraw.
+
+```
+erDiagram
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--|{ LINE-ITEM : contains
+  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/c1d3fdb3-32ef-4bf3-a38a-02ac3d7d2cb9"  width="300" height="200"/>
+
+```
+gitGraph
+  commit
+  commit
+  branch develop
+  checkout develop
+  commit
+  commit
+  checkout main
+  merge develop
+  commit
+  commit
+
+```
+
+<img src="https://github.com/excalidraw/excalidraw/assets/11256141/e5dcec0b-d570-4eb4-b981-412a996aa96c"  width="400" height="300"/>
-- 
cgit v1.2.3

