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, without any modifications:

---
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 enclosed by the %% markers
No frontmatter settings other than excalidraw-plugin: parsed may be used
File extension：.md

Mode 2: Standard Excalidraw Format

Output a plain JSON file directly, 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)
Plain JSON, no Markdown wrapper
File extension：.excalidraw

Mode 3: Animated Excalidraw Format

Same as Standard format, but add the customData.animate field to each element to control 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 for this element (milliseconds), default 500
Elements with the same order appear at the same time
Recommended order: title → main framework → connecting lines → detail text

How to use:

Generate the .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 diagram type to improve comprehension and visual appeal.

Type	English	Use case	Approach
Flowchart	Flowchart	Step explanations, workflows, task execution order	Connect the steps with arrows to clearly express the flow direction
Mind map	Mind Map	Concept expansion, topic categorization, inspiration capture	Radiate outward from a central core in a radial structure
Hierarchy diagram	Hierarchy	Organizational structure, content hierarchy, system decomposition	Build hierarchical nodes from top to bottom or left to right
Relationship diagram	Relationship	Influence, dependency, and interaction between elements	Use connecting lines between shapes to show relationships, with arrows and descriptions
Comparison chart	Comparison	Comparative analysis of two or more options or viewpoints	Use two columns or a table format, indicating the dimensions of comparison
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 two dimensions, X and Y, and place items on the coordinate plane
Free layout	Freeform	Scattered content, inspiration notes, preliminary information collection	No structural constraints; 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 minimum, below this value it is unreadable at normal zoom):
- Title: 20-28px (minimum 20px)
- Subtitle: 18-20px
- Body/labels: 16-18px (minimum 16px)
- Secondary notes: 14px (only for unimportant auxiliary explanations, use with caution)
- Absolutely forbidden below 14px
Line height: all text uses 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 information at different levels
Graphical elements: appropriately use rectangles, circles, arrows, and other elements to organize information
No Emoji: do not use any Emoji symbols in chart text; if visual markers are needed, use simple shapes (circles, squares, arrows) or color distinctions

Color Palette

Text color (strokeColor for text):

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

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

Color value	Semantics	Applicable scenarios
`#a5d8ff`	Light blue	Input, data sources, main nodes
`#b2f2bb`	Light green	Success, output, completed
`#ffd8a8`	Light orange	Warning, pending, external dependencies
`#d0bfff`	Light purple	In progress, middleware, special items
`#ffc9c9`	Light red	Error, critical, alert
`#fff3bf`	Light yellow	Notes, decisions, planning
`#c3fae8`	Light cyan	Storage, data, cache
`#eebefa`	Light pink	Analysis, metrics, statistics

Region background color (large rectangle + opacity: 30, used for layered charts):

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
On light-colored fills, use dark variants of the text (for example, on a light green background use #15803d, do not use #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 the 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 In Markdown, the sectionmust be left empty, using only %% as the separator
The Obsidian ExcaliDraw plugin will, based on the JSON data,automatically populate 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 range of 0-1200 x 0-800 pixels
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 properties (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 a standalone text element, the x is the left edge, not the center. It must be manually calculated using a 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 of spacing from surrounding elements
Insufficient canvas whitespace — content should not be placed against the canvas edge. Leave 50-80px of padding on all sides
Title 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 arrow length
Insufficient contrast — light-colored text is almost invisible on a white background. Text color should not be lighter than #757575, and colored text should use dark 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 an Excalidraw diagram,the following steps must be automatically performed：

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 filename

Choose the file extension based on the output mode:

Mode	Filename 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 detects 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 checks
All elements have a unique id
Include the appState and files: {} fields

6. User Feedback and Confirmation

Report to the user:

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

Example Output Messages