drawio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io Diagram Skill

Draw.io 图表技能

Generate draw.io diagrams as native

.drawio

files. Author each diagram either as Mermaid (concise text that the draw.io desktop CLI converts and lays out for you) or as draw.io XML directly. Optionally auto-layout XML-authored diagrams with ELK, export to PNG/SVG/PDF with the diagram XML embedded (so the exported file stays editable in draw.io), or generate a browser URL that opens the diagram directly in the draw.io editor.

生成原生

.drawio

文件格式的draw.io图表。可以通过Mermaid（一种简洁文本格式，draw.io桌面CLI会将其转换并自动布局）或直接通过draw.io XML来创作图表。还可选择使用ELK对XML创作的图表进行自动布局，将图表导出为嵌入了XML的PNG/SVG/PDF格式（这样导出的文件仍可在draw.io中编辑），或者生成可直接在draw.io编辑器中打开图表的浏览器URL。

Authoring: Mermaid or XML?

创作方式：选Mermaid还是XML？

The desktop CLI can convert Mermaid to a native

.drawio

file, so prefer Mermaid for the diagram types it handles well — its parser lays the diagram out automatically, which is far more reliable than hand-positioning cells in XML.

Author as	Best for	Needs desktop CLI?
Mermaid	Flowcharts, sequence, class, state, ER, gantt, mindmap, timeline, user journey, quadrant, C4, git graph, pie, and other standard types	Yes — to convert to `.drawio`
XML	Custom styling, precise/hand positioning, specific shape libraries (AWS, Azure, network, UML detail…), or when the desktop CLI is not installed	No (optional ELK `--layout` needs the CLI)

Prefer Mermaid when the desktop CLI is available and the request is one of the standard types above — write terse Mermaid and let draw.io lay it out.
Use XML for precise control, or as the universal fallback: XML needs no CLI at all, so it's the only option when the desktop app isn't installed (output a
```
.drawio
```
file or a
```
url
```
).
For XML-authored diagrams you can ask the CLI to apply an ELK auto-layout (
```
--layout
```
) instead of computing coordinates yourself — the same layouts the draw.io editor's Arrange ▸ Layout menu applies, and the same engine the draw.io MCP app server uses. See ELK layout for XML.

If you're unsure whether the desktop CLI is present, detect it first (see Locating the CLI). No CLI → author as XML and deliver a

.drawio

file or a

url

桌面CLI可以将Mermaid转换为原生

.drawio

文件，因此优先选择Mermaid来创作它擅长处理的图表类型——其解析器会自动完成图表布局，这比手动在XML中定位单元格要可靠得多。

创作方式	适用场景	是否需要桌面CLI？
Mermaid	流程图、时序图、类图、状态图、ER图、甘特图、思维导图、时间线、用户旅程图、四象限图、C4图、Git图、饼图及其他标准类型	是——用于转换为 `.drawio` 文件
XML	自定义样式、精准手动定位、特定形状库（AWS、Azure、网络、UML细节等），或未安装桌面CLI的场景	否（可选的ELK `--layout` 需要CLI）

当桌面CLI可用且需求属于上述标准类型时，优先使用Mermaid——编写简洁的Mermaid代码，让draw.io自动完成布局。
需要精准控制时，或作为通用 fallback 方案时使用XML：XML完全不需要CLI，因此是未安装桌面应用时的唯一选择（输出
```
.drawio
```
文件或
```
url
```
）。
对于XML创作的图表，你可以让CLI应用ELK自动布局（
```
--layout
```
），无需自行计算坐标——这与draw.io编辑器中「排列 ▸ 布局」菜单使用的布局方式相同，也和draw.io MCP应用服务器使用的引擎一致。详见XML的ELK布局。

如果你不确定桌面CLI是否存在，请先进行检测（详见定位CLI）。无CLI时→以XML创作并交付

.drawio

文件或

url

。

The pipeline

工作流程

Every diagram becomes a native

.drawio

file first, then is delivered in the requested output format. This keeps the delivery step identical whether you authored Mermaid or XML.

Author →
.drawio
- Mermaid: write the Mermaid to a
```
.mmd
```
  file, then convert it with the CLI:
  bash
```
drawio -x -f xml -o diagram.drawio diagram.mmd
```
  Delete the
```
.mmd
```
  afterward — the
```
.drawio
```
  is the artifact. draw.io's Mermaid parser has already laid the diagram out, so no
```
--layout
```
  is needed.
- XML: write the mxGraphModel XML to
```
diagram.drawio
```
  (see XML format). Optionally apply an ELK layout (see ELK layout for XML).
Deliver (identical for both sources):
- (no format) → keep
```
diagram.drawio
```
  and open it.
- png / svg / pdf → export from the
```
.drawio
```
  with embedded XML, then delete the source
```
.drawio
```
  :
  bash
```
drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio
```
- url → build a browser URL from the
```
.drawio
```
  XML, open it, and keep the
```
.drawio
```
  as a local copy (see Browser URL output).
Open the result — the exported file, the URL, or the
```
.drawio
```
. If the open command fails, print the absolute path (or URL) so the user can open it manually.

Always convert Mermaid to
.drawio
first, then export — do not export a

.mmd

straight to an image. Direct Mermaid → PNG export with

-e

is broken in current draw.io Desktop (the embedded-XML step crashes); the two-step path (convert, then export the

.drawio

) is reliable and produces an editable embed. See Troubleshooting.

If Mermaid was requested but no desktop CLI is available, fall back to authoring the same diagram directly as XML.

所有图表都会先转换为原生

.drawio

文件，再以请求的输出格式交付。无论你使用Mermaid还是XML创作，交付步骤都是相同的。

创作 →
.drawio
文件
- Mermaid：将Mermaid代码写入
```
.mmd
```
  文件，然后通过CLI转换：
  bash
```
drawio -x -f xml -o diagram.drawio diagram.mmd
```
  转换后删除
```
.mmd
```
  文件——
```
.drawio
```
  文件是最终产物。draw.io的Mermaid解析器已完成图表布局，因此无需使用
```
--layout
```
  。
- XML：将mxGraphModel XML写入
```
diagram.drawio
```
  （详见XML格式）。可选应用ELK布局（详见XML的ELK布局）。
交付（两种创作方式的交付步骤相同）：
- (未指定格式) → 保留
```
diagram.drawio
```
  文件并打开它。
- png / svg / pdf → 从
```
.drawio
```
  文件导出并嵌入XML，然后删除源
```
.drawio
```
  文件：
  bash
```
drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio
```
- url → 从
```
.drawio
```
  XML构建浏览器URL，打开该URL，并保留
```
.drawio
```
  文件作为本地副本（详见浏览器URL输出）。
打开结果——导出的文件、URL或
```
.drawio
```
文件。如果打开命令失败，请打印绝对路径（或URL）以便用户手动打开。

务必先将Mermaid转换为
.drawio
文件，再进行导出——不要直接将

.mmd

文件导出为图片。当前draw.io Desktop中直接从Mermaid→PNG导出（使用

-e

）存在问题（嵌入XML步骤会崩溃）；两步法（先转换为

.drawio

，再导出）更可靠，且能生成可编辑的嵌入内容。详见故障排查。

如果用户要求使用Mermaid但无桌面CLI可用，则直接以XML创作相同的图表。

ELK layout for XML

XML的ELK布局

XML-authored diagrams can be auto-positioned by the CLI's

--layout

pass — the same ELK layouts as the editor's Arrange ▸ Layout menu and the same engine the draw.io MCP app server uses. Generate the cells with approximate (or even

0,0

) positions and let ELK place them; you only have to get the graph structure — nodes and edges — right.

Add

--layout <name>

to any CLI call that reads your XML. The simplest form lays out in place after you write the file (reading and overwriting the same path is supported):

bash

drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio

Or combine layout with export in a single call (works for XML input):

bash

drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio

XML创作的图表可通过CLI的

--layout

命令自动定位——这与编辑器「排列 ▸ 布局」菜单使用的ELK布局相同，也和draw.io MCP应用服务器使用的引擎一致。生成单元格时可使用近似位置（甚至

0,0

），让ELK自动放置；你只需确保图表的结构——节点和连线——正确即可。

在任何读取XML的CLI命令中添加

--layout <名称>

。最简单的方式是写入文件后直接进行布局（支持读取并覆盖同一路径）：

bash

drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio

也可在单次调用中结合布局与导出（适用于XML输入）：

bash

drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio

Layout presets

布局预设

Name	Layout
`verticalFlow`	Layered, top-to-bottom — flowcharts, pipelines
`horizontalFlow`	Layered, left-to-right
`verticalTree`	Tree, top-down — hierarchies, org charts
`horizontalTree`	Tree, left-to-right
`radialTree`	Radial tree
`organic`	Force-directed — networks, mind-map-like graphs

名称	布局方式
`verticalFlow`	分层、自上而下——流程图、流水线
`horizontalFlow`	分层、自左至右
`verticalTree`	树形、自上而下——层级结构、组织架构图
`horizontalTree`	树形、自左至右
`radialTree`	放射状树形
`organic`	力导向布局——网络图、类思维导图的图表

Custom layout JSON

自定义布局JSON

For finer control, pass a JSON array (starting with

) instead of a preset name — the same format as the editor's custom-layout dialog:

bash

drawio -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio

Each entry is

{"layout": <algorithm>, "config": { … }}

Algorithms:

elkLayered

elkTree

elkRadial

elkOrganic

elkStress

elkBox

config
: keys starting with

elk.

are ELK options — e.g.

elk.direction

(

UP

DOWN

LEFT

RIGHT

elk.spacing.nodeNode

elk.layered.spacing.nodeNodeBetweenLayers

. The keys

edgeStyle

(e.g.

orthogonal

) and

corners

(e.g.

rounded

) control connector rendering.

如需更精细的控制，可传入JSON数组（以

开头）替代预设名称——格式与编辑器的自定义布局对话框相同：

bash

drawio -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio

每个数组项为

{"layout": <算法>, "config": { … }}

：

算法：

elkLayered

、

elkTree

、

elkRadial

、

elkOrganic

、

elkStress

、

elkBox

。

config
：以

elk.

开头的键为ELK选项——例如

elk.direction

（

UP

DOWN

LEFT

RIGHT

）、

elk.spacing.nodeNode

、

elk.layered.spacing.nodeNodeBetweenLayers

。

edgeStyle

（例如

orthogonal

）和

corners

（例如

rounded

）控制连线的渲染方式。

Orthogonal edge routing

正交连线路由

--layout libavoid

routes the edges orthogonally around the shapes (the editor's Arrange ▸ Layout ▸ Orthogonal Routing) without moving any vertex — the complement of the node layouts above. Use it as an in-place pass on hand-positioned XML whose connectors cross shapes:

bash

drawio -x -f xml --layout libavoid -o diagram.drawio diagram.drawio

Skip it after a flow/tree preset — those already route their edges.

When to use it: author the graph structure as XML without worrying about coordinates, then apply

verticalFlow

horizontalFlow

for flow-style diagrams or

organic

for networks. Mermaid-authored diagrams are already laid out — don't add

--layout

--layout libavoid

会让连线围绕形状进行正交路由（编辑器的「排列 ▸ 布局 ▸ 正交路由」），而不会移动任何顶点——这是上述节点布局的补充。可将其用于手动定位的XML图表，解决连线交叉形状的问题：

bash

drawio -x -f xml --layout libavoid -o diagram.drawio diagram.drawio

使用流/树形预设后无需再使用该命令——这些预设已完成连线路由。

使用时机：以XML创作图表结构时无需担心坐标，之后对流程类图表应用

verticalFlow

horizontalFlow

，对网络图应用

organic

。Mermaid创作的图表已完成布局——无需添加

--layout

。

Mermaid syntax reference

Mermaid语法参考

When authoring Mermaid, fetch and follow the shared Mermaid reference (all supported diagram types plus flowchart styling —

style

classDef

linkStyle

https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/mermaid-reference.md

Match the language of the diagram labels to the user's language.

创作Mermaid图表时，请参考并遵循共享的Mermaid参考文档（包含所有支持的图表类型及流程图样式——

style

、

classDef

、

linkStyle

）：

https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/mermaid-reference.md

图表标签的语言需与用户使用的语言一致。

Choosing the output format

选择输出格式

Check the user's request for a format preference. Examples:

/drawio:drawio create a flowchart

→ Mermaid →

flowchart.drawio

/drawio:drawio png flowchart for login

→ Mermaid →

login-flow.drawio.png

/drawio:drawio svg: ER diagram

→ Mermaid →

er-diagram.drawio.svg

/drawio:drawio pdf AWS architecture overview

→ XML (needs AWS shapes) →

architecture-overview.drawio.pdf

/drawio:drawio url flowchart for user login

→ opens browser at

app.diagrams.net

with the diagram, keeps

login-flow.drawio

locally

If no format is mentioned, just produce the

.drawio

file and open it in draw.io. The user can always ask to export later.

检查用户请求中的格式偏好。示例：

/drawio:drawio create a flowchart

→ Mermaid →

flowchart.drawio

/drawio:drawio png flowchart for login

→ Mermaid →

login-flow.drawio.png

/drawio:drawio svg: ER diagram

→ Mermaid →

er-diagram.drawio.svg

/drawio:drawio pdf AWS architecture overview

→ XML（需要AWS形状）→

architecture-overview.drawio.pdf

/drawio:drawio url flowchart for user login

→ 在浏览器中打开

app.diagrams.net

并加载该图表，本地保留

login-flow.drawio

文件

如果未提及格式，只需生成

.drawio

文件并在draw.io中打开。用户之后可随时要求导出。

Supported export formats

支持的导出格式

Format	Embed XML	Notes
`png`	Yes ( `-e` )	Viewable everywhere, editable in draw.io
`svg`	Yes ( `-e` )	Scalable, editable in draw.io
`pdf`	Yes ( `-e` )	Printable, editable in draw.io
`jpg`	No	Lossy, no embedded XML support

PNG, SVG, and PDF all support

--embed-diagram

— the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.

格式	嵌入XML	说明
`png`	是（ `-e` ）	可在任何地方查看，可在draw.io中编辑
`svg`	是（ `-e` ）	可缩放，可在draw.io中编辑
`pdf`	是（ `-e` ）	可打印，可在draw.io中编辑
`jpg`	否	有损压缩，不支持嵌入XML

PNG、SVG和PDF均支持

--embed-diagram

——导出的文件包含完整的图表XML，在draw.io中打开即可恢复可编辑的图表。

Browser URL output

浏览器URL输出

When the user requests

url

format, generate a draw.io URL that opens the diagram directly in the browser editor at

app.diagrams.net

— no draw.io Desktop required to view it. (Mermaid-authored diagrams still need the desktop CLI to convert to

.drawio

first; if no CLI is available, author the diagram as XML and build the URL from that.)

当用户要求

url

格式时，生成draw.io URL，可直接在浏览器编辑器

app.diagrams.net

中打开图表——查看图表无需draw.io Desktop。（Mermaid创作的图表仍需桌面CLI先转换为

.drawio

文件；如果无CLI可用，则直接以XML创作图表并基于XML构建URL。）

How it works

工作原理

The
```
.drawio
```
file is written to disk as usual (gives the user a persistent local copy they can re-edit)
The XML is compressed with Node.js's built-in
```
zlib
```
and base64-encoded
The result is embedded in a
```
https://app.diagrams.net/#create=...
```
URL
The URL is opened in the default browser

This uses only Node.js built-in modules (

zlib

child_process

) — no external dependencies.

按常规将
```
.drawio
```
文件写入磁盘（为用户提供可重新编辑的持久本地副本）
使用Node.js内置的
```
zlib
```
压缩XML并进行base64编码
将结果嵌入
```
https://app.diagrams.net/#create=...
```
URL
在默认浏览器中打开该URL

此过程仅使用Node.js内置模块（

zlib

、

child_process

）——无外部依赖。

URL generation

URL生成

Run this

node -e

one-liner to read the

.drawio

file and print the URL (replace

DIAGRAM.drawio

with the actual filename):

bash

URL=$(node -e '
const fs = require("fs");
const zlib = require("zlib");
const xml = fs.readFileSync(process.argv[1], "utf8");
const compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString("base64");
const payload = encodeURIComponent(JSON.stringify({ type: "xml", compressed: true, data: compressed }));
console.log("https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#create=" + payload);
' "DIAGRAM.drawio")

The URL format matches the MCP Tool Server. Node.js's

zlib.deflateRawSync

and

pako.deflateRaw

both implement RFC 1951 and produce identical output, so URLs from either source are interchangeable.

运行以下

node -e

单行命令读取

.drawio

文件并打印URL（将

DIAGRAM.drawio

替换为实际文件名）：

bash

URL=$(node -e '
const fs = require("fs");
const zlib = require("zlib");
const xml = fs.readFileSync(process.argv[1], "utf8");
const compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString("base64");
const payload = encodeURIComponent(JSON.stringify({ type: "xml", compressed: true, data: compressed }));
console.log("https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#create=" + payload);
' "DIAGRAM.drawio")

URL格式与MCP工具服务器一致。Node.js的

zlib.deflateRawSync

和

pako.deflateRaw

均实现了RFC 1951，输出结果相同，因此两种方式生成的URL可互换使用。

Opening the URL

打开URL

Environment	Command
macOS	`open "$URL"`
Linux (native)	`xdg-open "$URL"`
WSL2	Write a temp `.url` file, open via `cmd.exe` (see below)
Windows (native)	Write a temp `.url` file, open via `start` (see below)

Why the
.url
workaround on Windows/WSL2?

cmd.exe

start

command treats

as a command separator and strips everything after

in URLs. The diagram payload lives in the

#create=...

fragment, so passing the URL directly causes it to be silently lost. A

.url

shortcut file preserves the URL intact.

macOS / Linux example:

bash

open "$URL"      # macOS
xdg-open "$URL"  # Linux

WSL2 example:

bash

TMPFILE=$(mktemp --suffix=.url)
printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMPFILE"
cmd.exe /c start "" "$(wslpath -w "$TMPFILE")"

Windows (native) example:

Do not build the

.url

file with

echo URL=%URL%

. The generated URL contains

characters (

?grid=0&pv=0&...

) that

cmd.exe

treats as command separators, so the shortcut is written truncated and the diagram payload is lost — the exact failure the

.url

file is meant to prevent. Let Node write the file directly (it already holds the URL string) and open only the resulting path, which never contains

bash

TMPFILE=$(node -e '
const fs = require("fs");
const os = require("os");
const path = require("path");
const p = path.join(os.tmpdir(), "drawio.url");
fs.writeFileSync(p, "[InternetShortcut]\r\nURL=" + process.argv[1] + "\r\n");
process.stdout.write(p);
' "$URL")
cmd.exe /c start "" "$TMPFILE"

环境	命令
macOS	`open "$URL"`
Linux（原生）	`xdg-open "$URL"`
WSL2	写入临时 `.url` 文件，通过 `cmd.exe` 打开（详见下文）
Windows（原生）	写入临时 `.url` 文件，通过 `start` 打开（详见下文）

为什么Windows/WSL2需要
.url
变通方案？

cmd.exe

的

start

命令会将

视为命令分隔符，并删除URL中

之后的所有内容。图表负载位于

#create=...

片段中，因此直接传递URL会导致负载丢失。

.url

快捷方式文件可完整保留URL。

macOS / Linux示例：

bash

open "$URL"      # macOS
xdg-open "$URL"  # Linux

WSL2示例：

bash

TMPFILE=$(mktemp --suffix=.url)
printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMPFILE"
cmd.exe /c start "" "$(wslpath -w "$TMPFILE")"

Windows（原生）示例：

请勿使用

echo URL=%URL%

构建

.url

文件。生成的URL包含

字符（

?grid=0&pv=0&...

），

cmd.exe

会将其视为命令分隔符，导致快捷方式文件被截断，图表负载丢失——这正是

.url

文件要解决的问题。让Node.js直接写入文件（它已持有完整的URL字符串），然后仅打开生成的路径，该路径绝不会包含

：

bash

TMPFILE=$(node -e '
const fs = require("fs");
const os = require("os");
const path = require("path");
const p = path.join(os.tmpdir(), "drawio.url");
fs.writeFileSync(p, "[InternetShortcut]\r\nURL=" + process.argv[1] + "\r\n");
process.stdout.write(p);
' "$URL")
cmd.exe /c start "" "$TMPFILE"

After opening

打开后操作

Print the URL so the user can copy or share it, and confirm the local file path:

Opened in browser: <URL>
Local file: DIAGRAM.drawio

The

.drawio

file stays on disk so the user can re-edit it later, attach it elsewhere, or export it to an image format on demand.

打印URL以便用户复制或分享，并确认本地文件路径：

已在浏览器中打开：<URL>
本地文件：DIAGRAM.drawio

.drawio

文件会保留在磁盘上，方便用户之后重新编辑、附加到其他位置或按需导出为图片格式。

URL length

URL长度

The URL embeds the full compressed diagram in its hash fragment. Very large diagrams may hit browser URL length limits (typically ~32K–2MB depending on the browser). For complex diagrams that exceed the limit, fall back to writing the

.drawio

file and opening it locally.

URL会在哈希片段中嵌入完整的压缩图表。非常大的图表可能会超出浏览器URL长度限制（通常约32K–2MB，取决于浏览器）。对于超出限制的复杂图表，退而求其次，写入

.drawio

文件并在本地打开。

draw.io CLI

The draw.io desktop app includes a command-line interface used for converting Mermaid to

.drawio

, applying ELK layouts (

--layout

), and exporting to PNG/SVG/PDF. All three require the desktop app to be installed.

draw.io桌面应用包含命令行界面，用于将Mermaid转换为
.drawio
文件、应用ELK布局（

--layout

）以及导出为PNG/SVG/PDF格式。这三个功能都需要安装桌面应用。

Locating the CLI

定位CLI

First, detect the environment, then locate the CLI accordingly:

首先检测环境，然后据此定位CLI：

WSL2 (Windows Subsystem for Linux)

WSL2（Windows子系统Linux）

WSL2 is detected when

/proc/version

contains

microsoft

WSL

bash

grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"

On WSL2, use the Windows draw.io Desktop executable via

/mnt/c/...

bash

DRAWIO_CMD="/mnt/c/Program Files/draw.io/draw.io.exe"

Double-quote the path so the space in

Program Files

is treated as part of the path. Do not wrap it in backticks — in bash, backticks are command substitution, which would try to execute the binary at locate-time instead of storing its path.

If draw.io is installed in a non-default location, check common alternatives:

bash

undefined

当

/proc/version

包含

microsoft

或

WSL

时，可检测到WSL2：

bash

grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"

在WSL2中，通过

/mnt/c/...

使用Windows版draw.io Desktop可执行文件：

bash

DRAWIO_CMD="/mnt/c/Program Files/draw.io/draw.io.exe"

路径需用双引号包裹，以便

Program Files

中的空格被视为路径的一部分。请勿使用反引号——在bash中，反引号是命令替换，会在定位时尝试执行二进制文件，而非存储其路径。

如果draw.io安装在非默认位置，请检查常见替代路径：

bash

undefined

Default install path

默认安装路径

"/mnt/c/Program Files/draw.io/draw.io.exe"

Per-user install (if the above does not exist)

按用户安装（如果上述路径不存在）

"/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe"

undefined

"/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe"

undefined

macOS

bash

/Applications/draw.io.app/Contents/MacOS/draw.io

bash

/Applications/draw.io.app/Contents/MacOS/draw.io

Linux (native)

Linux（原生）

bash

drawio   # typically on PATH via snap/apt/flatpak

bash

drawio   # 通常通过snap/apt/flatpak安装在PATH中

Windows (native, non-WSL2)

Windows（原生，非WSL2）

"C:\Program Files\draw.io\draw.io.exe"

Use

which drawio

(or

where draw.io

on Windows) to check if it's on PATH before falling back to the platform-specific path.

"C:\Program Files\draw.io\draw.io.exe"

在使用平台特定路径之前，先使用

which drawio

（Windows中使用

where draw.io

）检查它是否在PATH中。

Convert / layout / export commands

转换/布局/导出命令

Convert Mermaid to
.drawio
:

bash

drawio -x -f xml -o diagram.drawio diagram.mmd

Apply an ELK layout to XML (see ELK layout for XML):

bash

drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio

Export to an image format:

bash

drawio -x -f <format> -e -b 10 -o "<output>" "<input.drawio>"

WSL2 export example:

bash

"/mnt/c/Program Files/draw.io/draw.io.exe" -x -f png -e -b 10 -o "diagram.drawio.png" "diagram.drawio"

Key flags:

```
-x
```
/
```
--export
```
: export mode (also used for Mermaid conversion and layout passes)
```
-f
```
/
```
--format
```
: output format (
```
xml
```
, png, svg, pdf, jpg) — use
```
xml
```
to produce a
```
.drawio
```
from Mermaid or a layout pass
```
--layout
```
: run a layout before writing the output — an ELK preset name, the
```
libavoid
```
edge-routing pass, or a custom-layout JSON array
```
--mermaid-image 1
```
: convert Mermaid to a single static SVG image cell (the Mermaid source stays on the cell for re-editing) instead of an editable diagram — only when the user explicitly asks for a non-editable image cell
```
-e
```
/
```
--embed-diagram
```
: embed diagram XML in the output (PNG, SVG, PDF only)
```
-o
```
/
```
--output
```
: output file path
```
-b
```
/
```
--border
```
: border width around diagram (default: 0)
```
-t
```
/
```
--transparent
```
: transparent background (PNG only)
```
-s
```
/
```
--scale
```
: scale the diagram size
```
--width
```
/
```
--height
```
: fit into specified dimensions (preserves aspect ratio)
```
-a
```
/
```
--all-pages
```
: export all pages (PDF only)
```
-p
```
/
```
--page-index
```
: select a specific page (1-based)

将Mermaid转换为
.drawio
文件：

bash

drawio -x -f xml -o diagram.drawio diagram.mmd

对XML应用ELK布局（详见XML的ELK布局）：

bash

drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio

导出为图片格式：

bash

drawio -x -f <format> -e -b 10 -o "<output>" "<input.drawio>"

WSL2导出示例：

bash

"/mnt/c/Program Files/draw.io/draw.io.exe" -x -f png -e -b 10 -o "diagram.drawio.png" "diagram.drawio"

关键参数：

```
-x
```
/
```
--export
```
：导出模式（也用于Mermaid转换和布局操作）
```
-f
```
/
```
--format
```
：输出格式（
```
xml
```
、png、svg、pdf、jpg）——从Mermaid转换或布局操作生成
```
.drawio
```
文件时使用
```
xml
```
```
--layout
```
：写入输出前运行布局——ELK预设名称、
```
libavoid
```
连线路由操作，或自定义布局JSON数组
```
--mermaid-image 1
```
：将Mermaid转换为单个静态SVG图片单元格（Mermaid源会保留在单元格中以便重新编辑），而非可编辑的图表——仅当用户明确要求不可编辑的图片单元格时使用
```
-e
```
/
```
--embed-diagram
```
：在输出中嵌入图表XML（仅适用于PNG、SVG、PDF）
```
-o
```
/
```
--output
```
：输出文件路径
```
-b
```
/
```
--border
```
：图表周围的边框宽度（默认：0）
```
-t
```
/
```
--transparent
```
：透明背景（仅适用于PNG）
```
-s
```
/
```
--scale
```
：缩放图表大小
```
--width
```
/
```
--height
```
：适配指定尺寸（保持宽高比）
```
-a
```
/
```
--all-pages
```
：导出所有页面（仅适用于PDF）
```
-p
```
/
```
--page-index
```
：选择特定页面（从1开始计数）

Opening the result

打开结果

Environment	Command
macOS	`open <file>`
Linux (native)	`xdg-open <file>`
WSL2	`cmd.exe /c start "" "$(wslpath -w <file>)"`
Windows	`start <file>`

WSL2 notes:

```
wslpath -w <file>
```
converts a WSL2 path (e.g.
```
/home/user/diagram.drawio
```
) to a Windows path (e.g.
```
C:\Users\...
```
). This is required because
```
cmd.exe
```
cannot resolve
```
/mnt/c/...
```
style paths.
The empty string
```
""
```
after
```
start
```
is required to prevent
```
start
```
from interpreting the filename as a window title.

WSL2 example:

bash

cmd.exe /c start "" "$(wslpath -w diagram.drawio)"

环境	命令
macOS	`open <file>`
Linux（原生）	`xdg-open <file>`
WSL2	`cmd.exe /c start "" "$(wslpath -w <file>)"`
Windows	`start <file>`

WSL2注意事项：

```
wslpath -w <file>
```
将WSL2路径（例如
```
/home/user/diagram.drawio
```
）转换为Windows路径（例如
```
C:\Users\...
```
）。这是必需的，因为
```
cmd.exe
```
无法解析
```
/mnt/c/...
```
格式的路径。
```
start
```
后的空字符串
```
""
```
是必需的，可防止
```
start
```
将文件名解释为窗口标题。

WSL2示例：

bash

cmd.exe /c start "" "$(wslpath -w diagram.drawio)"

File naming

文件命名

Use a descriptive filename based on the diagram content (e.g.,
```
login-flow
```
,
```
database-schema
```
)
Use lowercase with hyphens for multi-word names
When authoring Mermaid, write it to a matching
```
.mmd
```
file, convert to
```
.drawio
```
, then delete the
```
.mmd
```
— the
```
.drawio
```
is the artifact
For export, use double extensions:
```
name.drawio.png
```
,
```
name.drawio.svg
```
,
```
name.drawio.pdf
```
— this signals the file contains embedded diagram XML
After a successful export, delete the intermediate
```
.drawio
```
file — the exported file contains the full diagram
For
```
url
```
mode, keep the
```
.drawio
```
file (no double extension) — the URL is a view/edit handle and the local file is the persistent copy

根据图表内容使用描述性文件名（例如
```
login-flow
```
、
```
database-schema
```
）
多词名称使用小写字母加连字符
创作Mermaid时，将代码写入对应的
```
.mmd
```
文件，转换为
```
.drawio
```
文件后删除
```
.mmd
```
文件——
```
.drawio
```
文件是最终产物
导出时使用双重扩展名：
```
name.drawio.png
```
、
```
name.drawio.svg
```
、
```
name.drawio.pdf
```
——这表明文件包含嵌入的图表XML
导出成功后，删除中间
```
.drawio
```
文件——导出的文件包含完整的图表
```
url
```
模式下，保留
```
.drawio
```
文件（不使用双重扩展名）——URL是查看/编辑入口，本地文件是持久副本

XML format

XML格式

.drawio

file is native mxGraphModel XML. When authoring as XML, generate it directly; Mermaid is converted to this same format by the CLI (

-f xml

), so both authoring routes end up as a native

.drawio

.drawio

文件是原生mxGraphModel XML。以XML创作时，直接生成该格式；Mermaid会被CLI转换为相同格式（

-f xml

），因此两种创作方式最终都会生成原生

.drawio

文件。

Basic structure

基本结构

Every diagram must have this structure:

xml

<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- Diagram cells go here with parent="1" -->
  </root>
</mxGraphModel>

Cell
```
id="0"
```
is the root layer
Cell
```
id="1"
```
is the default parent layer
All diagram elements use
```
parent="1"
```
unless using multiple layers

(The example above uses an XML comment only to point out where cells go — never emit comments in real output; see XML well-formedness.)

每个图表必须具有以下结构：

xml

<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- Diagram cells go here with parent="1" -->
  </root>
</mxGraphModel>

单元格
```
id="0"
```
是根图层
单元格
```
id="1"
```
是默认父图层
所有图表元素使用
```
parent="1"
```
，除非使用多个图层

（上述示例中的XML注释仅用于指出单元格的位置——实际输出中绝不要包含注释；详见XML格式正确性。）

XML reference

XML参考

For the complete draw.io XML reference including common styles, edge routing, containers, layers, tags, metadata, dark mode colors, and XML well-formedness rules, fetch and follow the instructions at: https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md

如需完整的draw.io XML参考，包括常见样式、连线路由、容器、图层、标签、元数据、深色模式颜色和XML格式规则，请参考以下链接中的说明： https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md

Troubleshooting

故障排查

Problem	Cause	Solution
draw.io CLI not found	Desktop app not installed or not on PATH	Author as XML and deliver a `.drawio` file or `url` (Mermaid conversion, ELK layout, and image export all need the desktop app). Tell the user they can install the draw.io desktop app to enable those
Mermaid → PNG export crashes	Direct `.mmd` → PNG with `-e` is broken in current draw.io Desktop (embedded-XML step)	Use the two-step path: convert Mermaid to `.drawio` first ( `-f xml` ), then export the `.drawio` to PNG — the intermediate file embeds correctly
Blank diagram from Mermaid	Misspelled type keyword, or a syntax error (bad node ID, unquoted label)	Check the Mermaid reference; the first non-directive line's keyword selects the diagram type
Layout does nothing / errors	Unknown preset name, custom JSON not an array, or a desktop build too old for `--layout` / `.mmd` input	Use a preset from Layout presets or a JSON array starting with `[` ; on an old desktop build, author as XML with explicit positions and tell the user updating draw.io Desktop enables Mermaid conversion and layouts
Export produces empty/corrupt file	Invalid XML (e.g. double hyphens in comments, unescaped special characters)	Validate XML well-formedness before writing; see the XML well-formedness section below
Diagram opens but looks blank	Missing root cells `id="0"` and `id="1"`	Ensure the basic mxGraphModel structure is complete
Edges not rendering	Edge mxCell is self-closing (no child mxGeometry element)	Every edge must have `<mxGeometry relative="1" as="geometry" />` as a child element
File won't open after export	Incorrect file path or missing file association	Print the absolute file path so the user can open it manually
Browser opens with empty diagram in `url` mode	`cmd.exe` stripped the `#create=...` fragment	Use the `.url` temp-file workaround on Windows/WSL2 (see Opening the URL) — never pass the URL directly to `cmd.exe /c start`
URL is too long for the browser	Very large diagram exceeds browser URL length limit	Fall back to writing the `.drawio` file and opening it locally

问题	原因	解决方案
未找到draw.io CLI	未安装桌面应用或应用不在PATH中	以XML创作并交付 `.drawio` 文件或 `url` （Mermaid转换、ELK布局和图片导出都需要桌面应用）。告知用户安装draw.io桌面应用即可启用这些功能
Mermaid→PNG导出崩溃	当前draw.io Desktop中直接从 `.mmd` →PNG导出（使用 `-e` ）存在问题（嵌入XML步骤崩溃）	使用两步法：先将Mermaid转换为 `.drawio` 文件（ `-f xml` ），再将 `.drawio` 文件导出为PNG——中间文件可正确嵌入内容
Mermaid生成空白图表	类型关键字拼写错误，或存在语法错误（节点ID无效、标签未加引号）	查看Mermaid语法参考；第一行非指令代码的关键字决定了图表类型
布局无效果/报错	预设名称未知、自定义JSON不是数组，或桌面版本过旧不支持 `--layout` / `.mmd` 输入	使用布局预设中的预设，或使用以 `[` 开头的JSON数组；如果桌面版本过旧，以XML创作并指定明确位置，告知用户更新draw.io Desktop即可启用Mermaid转换和布局功能
导出生成空文件/损坏文件	XML无效（例如注释中包含双连字符、特殊字符未转义）	写入前验证XML格式正确性；详见下文的XML格式正确性部分
图表可打开但显示空白	缺少根单元格 `id="0"` 和 `id="1"`	确保mxGraphModel基本结构完整
连线未渲染	连线mxCell是自闭合的（无子mxGeometry元素）	每个连线必须包含 `<mxGeometry relative="1" as="geometry" />` 作为子元素
导出后文件无法打开	文件路径错误或缺少文件关联	打印绝对文件路径以便用户手动打开
`url` 模式下浏览器打开空白图表	`cmd.exe` 删除了 `#create=...` 片段	在Windows/WSL2中使用 `.url` 临时文件变通方案（详见打开URL）——绝不要直接将URL传递给 `cmd.exe /c start`
URL过长超出浏览器限制	超大图表超出浏览器URL长度限制	退而求其次，写入 `.drawio` 文件并在本地打开

CRITICAL: XML well-formedness

关键：XML格式正确性

NEVER include ANY XML comments (

) in the output. XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
Escape special characters in attribute values:
```
&amp;
```
,
```
&lt;
```
,
```
&gt;
```
,
```
&quot;
```
Always use unique
```
id
```
values for each
```
mxCell
```

输出中绝不要包含任何XML注释（

）。XML注释是严格禁止的——它们会浪费令牌，可能导致解析错误，且在图表XML中毫无用处。
转义属性值中的特殊字符：
```
&amp;
```
、
```
&lt;
```
、
```
&gt;
```
、
```
&quot;
```
每个
```
mxCell
```
必须使用唯一的
```
id
```
值