excalidraw-diagram

Excalidraw Diagram Generator

Create Excalidraw diagrams from text content with multiple output formats.

Output Modes

Select the output mode based on the user's trigger word:

Trigger word	Output mode	File format	Purpose
`Excalidraw`、`画图`、`流程图`、`思维导图`	Obsidian(Default)	`.md`	Open directly in Obsidian
`标准Excalidraw`、`standard excalidraw`	Standard	`.excalidraw`	Open/edit/share on excalidraw.com
`Excalidraw动画`、`动画图`、`animate`	Animated	`.excalidraw`	Drag to excalidraw-animate to generate an animation

Workflow

Detect output mode from trigger words (see Output Modes table above)
Analyze content - identify concepts, relationships, hierarchy
Choose diagram type (see Diagram Types below)
Generate Excalidraw JSON (add animation order if Animated mode)
Output in correct format based on mode
Automatically save to current working directory
Notify user with file path and usage instructions

Output Formats

Mode 1: Obsidian Format (Default)

Output strictly according to the following structure, with no modifications allowed:

---
excalidraw-plugin: parsed
tags: [excalidraw]
---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'

# Excalidraw Data

## Text Elements
%%
## Drawing
\`\`\`json
{JSON 完整数据}
\`\`\`
%%

Key points:

Frontmatter must include tags: [excalidraw]
The warning message must be complete
JSON must be %% surrounded by markers
Cannot use excalidraw-plugin: parsed frontmatter settings other than
File extension：.md

Mode 2: Standard Excalidraw Format

Directly output a pure JSON file, which can be opened on excalidraw.com:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "gridSize": null,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

Key points:

source Use https://excalidraw.com(not the Obsidian plugin)
Pure JSON, no Markdown wrapper
File extension：.excalidraw

Mode 3: Animated Excalidraw Format

Same as the Standard format, but add customData.animate field to each element to control the animation order:

{
  "id": "element-1",
  "type": "rectangle",
  "customData": {
    "animate": {
      "order": 1,
      "duration": 500
    }
  },
  ...其他标准字段
}

Animation order rules:

order: Animation playback order (1, 2, 3...), the smaller the number, the earlier it appears
duration: The drawing duration of this element (milliseconds), default 500
Elements with the same order appear at the same time
Suggested order: title → main framework → connecting lines → detail text

How to use:

Generate .excalidraw file
Drag to https://dai-shi.github.io/excalidraw-animate/
Click Animate to preview, then export SVG or WebM

File extension：.excalidraw

Diagram Types & Selection Guide

Choose the appropriate chart type to improve comprehension and visual appeal.

Type	English	Use case	Approach
Flowchart	Flowchart	Step descriptions, workflows, task execution order	Connect each step with arrows to clearly express the flow direction
Mind map	Mind Map	Concept divergence, topic classification, inspiration capture	Diverge outward from the center as the core, in a radial structure
Hierarchy diagram	Hierarchy	Organizational structure, content hierarchy, system decomposition	Build hierarchical nodes from top to bottom or from left to right
Relationship diagram	Relationship	Influence, dependency, and interaction between elements	Use connecting lines between shapes to show associations, arrows and descriptions
Comparison diagram	Comparison	Comparative analysis of two or more options or viewpoints	Two columns on the left and right or a table format, indicating comparison dimensions
Timeline diagram	Timeline	Event development, project progress, model evolution	Use time as the axis, marking key time points and events
Matrix diagram	Matrix	Two-dimensional classification, task priority, positioning	Establish X and Y dimensions, place on a coordinate plane
Free layout	Freeform	Scattered content, inspiration notes, preliminary information collection	No structural restrictions, freely place blocks and arrows

Design Rules

Text & Format

All text elements must use fontFamily: 5(Excalifont handwriting font)
Double quote replacement rule in text：" replace with 『』
Parenthesis replacement rule in text：() replace with 「」
Font size rules(Hard lower limit; below this value it is unreadable at normal zoom):
- Title: 20-28px (minimum 20px)
- Subtitle: 18-20px
- Body/label: 16-18px (minimum 16px)
- Secondary note: 14px (only for unimportant auxiliary explanations, use with caution)
- Absolutely forbidden below 14px
Line height: Use for all text lineHeight: 1.25
Text centering estimation: Standalone text elements are not automatically centered; the x coordinate must be calculated manually:
- Estimate text width:estimatedWidth = text.length * fontSize * 0.5(For CJK characters use * 1.0）
- Centering formula:x = centerX - estimatedWidth / 2
- Example: text "Hello" (5 characters, fontSize 20) centered at x=300 → estimatedWidth = 5 * 20 * 0.5 = 50 → x = 300 - 25 = 275

Layout & Design

Canvas range: It is recommended that all elements be within the 0-1200 x 0-800 area
Minimum shape size: Rectangles/ellipses with text should be no smaller than 120x60px
Element spacing: Minimum 20-30px spacing to prevent overlap
Clear hierarchy: Use different colors and shapes to distinguish different levels of information
Graphic elements: Appropriately use rectangles, circles, arrows, and other elements to organize information
Emoji prohibited: Do not use any Emoji symbols in chart text. If visual markers are needed, use simple shapes (circles, squares, arrows) or color distinction

Color Palette

Text color (strokeColor for text):

Purpose	Color value	Description
Title	`#1e40af`	Dark blue
Subtitle/connector line	`#3b82f6`	Bright blue
Body text	`#374151`	Dark gray (on a white background, the lightest should be no lighter than `#757575`）
Emphasis/key point	`#f59e0b`	Gold

Shape fill color (backgroundColor, fillStyle: "solid"):

Color value	Semantics	Applicable scenarios
`#a5d8ff`	Light blue	Input, data source, primary node
`#b2f2bb`	Light green	Success, output, completed
`#ffd8a8`	Light orange	Warning, pending, external dependency
`#d0bfff`	Light purple	Processing, middleware, special item
`#ffc9c9`	Light red	Error, critical, alert
`#fff3bf`	Light yellow	Note, decision, planning
`#c3fae8`	Light cyan	Storage, data, cache
`#eebefa`	Light pink	Analysis, metrics, statistics

Area background color (large rectangle + opacity: 30, used for layered diagrams):

Color value	Semantics
`#dbe4ff`	Frontend/UI layer
`#e5dbff`	Logic/processing layer
`#d3f9d8`	Data/tool layer

Contrast rules:

On a white background, text should be no lighter than #757575, otherwise it is unreadable
Use dark variants as text on light fills (e.g., on a light green background use #15803d, no need to #22c55e）
Avoid light gray text (#b0b0b0、#999) appearing on a white background

Reference:references/excalidraw-schema.md

JSON Structure

Obsidian mode:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://github.com/zsviczian/obsidian-excalidraw-plugin",
  "elements": [...],
  "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" },
  "files": {}
}

Standard / Animated mode:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" },
  "files": {}
}

Element Template

Each element requires these fields (do NOT add extra fields like frameId, index, versionNonce, rawText -- they may cause issues on excalidraw.com. boundElements must be null not [], updated must be 1 not timestamps):

{
  "id": "unique-id",
  "type": "rectangle",
  "x": 100, "y": 100,
  "width": 200, "height": 50,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "roundness": {"type": 3},
  "seed": 123456789,
  "version": 1,
  "isDeleted": false,
  "boundElements": null,
  "updated": 1,
  "link": null,
  "locked": false
}

strokeStyle values: "solid"(solid line, default) | "dashed"(dashed line) | "dotted"(dotted line). Dashed lines are suitable for representing optional paths, asynchronous flows, weak associations, etc.

Text elements add:

{
  "text": "显示文本",
  "fontSize": 20,
  "fontFamily": 5,
  "textAlign": "center",
  "verticalAlign": "middle",
  "containerId": null,
  "originalText": "显示文本",
  "autoResize": true,
  "lineHeight": 1.25
}

Animated mode additionally adds customData field:

{
  "id": "title-1",
  "type": "text",
  "customData": {
    "animate": {
      "order": 1,
      "duration": 500
    }
  },
  ...其他字段
}

See references/excalidraw-schema.md for all element types.

Additional Technical Requirements

Text Elements handling

## Text Elements section in Markdownmust be left empty, only use %% as the separator
The Obsidian ExcaliDraw plugin will, based on the JSON data,automatically fill in text elements
There is no need to manually list all text content

Coordinates and Layout

Coordinate system: the top-left corner is the origin (0,0)
Recommended range: all elements within the 0-1200 x 0-800 pixel range
Element ID: each element requires a unique id(can be a string, such as "title" "box1", etc.)

Required Fields for All Elements

IMPORTANT: Do NOT include frameId, index, versionNonce, or rawText fields. Use boundElements: null (not []), and updated: 1 (not timestamps).

{
  "id": "unique-identifier",
  "type": "rectangle|text|arrow|ellipse|diamond",
  "x": 100, "y": 100,
  "width": 200, "height": 50,
  "angle": 0,
  "strokeColor": "#color-hex",
  "backgroundColor": "transparent|#color-hex",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid|dashed|dotted",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "roundness": {"type": 3},
  "seed": 123456789,
  "version": 1,
  "isDeleted": false,
  "boundElements": null,
  "updated": 1,
  "link": null,
  "locked": false
}

Text-Specific Properties

Text elements (type: "text") require additional attributes (do NOT include rawText）：

{
  "text": "显示文本",
  "fontSize": 20,
  "fontFamily": 5,
  "textAlign": "center",
  "verticalAlign": "middle",
  "containerId": null,
  "originalText": "显示文本",
  "autoResize": true,
  "lineHeight": 1.25
}

appState configuration

"appState": {
  "gridSize": null,
  "viewBackgroundColor": "#ffffff"
}

files field

"files": {}

Common Mistakes to Avoid

Text offset — for standalone text elements, x is the left edge, not the center. You must manually calculate it using the centering formula, otherwise the text will be offset to one side
Element overlap — elements with similar y coordinates tend to stack. Before placing a new element, check whether there is at least 20px spacing from surrounding elements
Insufficient canvas whitespace — content should not be placed right against the canvas edge. Leave 50-80px of padding on all sides
Title is not centered on the diagram — the title should be centered on the overall width of the diagram below, not fixed at x=0
Arrow label overflow — long text labels (such as "ATP + NADPH") will extend beyond short arrows. Keep labels short or increase the arrow length
Insufficient contrast — light-colored text is almost invisible on a white background. Text color should be no lighter than #757575, and colored text should use darker variants
Font size too small — below 14px is unreadable at normal zoom; body text should be at least 16px

Implementation Notes

Auto-save & File Generation Workflow

When generating Excalidraw diagrams,the following steps must be performed automatically：

1. Choose an appropriate diagram type

Based on the characteristics of the content provided by the user, refer to the "Diagram Types & Selection Guide" table above
Analyze the core requirements of the content and choose the most appropriate visualization form

2. Generate a meaningful file name

Choose the file extension based on the output mode:

Mode	File name format	Example
Obsidian	`[主题].[类型].md`	`商业模式.relationship.md`
Standard	`[主题].[类型].excalidraw`	`商业模式.relationship.excalidraw`
Animated	`[主题].[类型].animate.excalidraw`	`商业模式.relationship.animate.excalidraw`

Prefer using Chinese to improve clarity

3. Use the Write tool to automatically save the file

Save location: the current working directory (automatically detect environment variables)
Full path：{current_directory}/[filename].md
This allows flexible migration without hardcoded paths

4. Ensure the Markdown structure is completely correct

Must be generated in the following format(no modifications allowed):

---
excalidraw-plugin: parsed
tags: [excalidraw]
---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'

# Excalidraw Data

## Text Elements
%%
## Drawing
\`\`\`json
{完整的 JSON 数据}
\`\`\`
%%

5. JSON Data Requirements

Include the complete Excalidraw JSON structure
All text elements use fontFamily: 5
In the text, " is replaced with 『』
In the text, () is replaced with 「」
The JSON format must be valid and pass syntax checking
All elements have unique id
Include appState and files: {} fields

6. User Feedback and Confirmation

Report to the user:

The diagram has been generated
The exact save location
How to view it in Obsidian
An explanation of the diagram's design choices (what type of diagram was chosen and why)
Whether adjustments or modifications are needed

Example Output Messages