beautiful-mermaid

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beautiful Mermaid Diagram Rendering

Beautiful Mermaid图表渲染

Render Mermaid diagrams as SVG and PNG images using the Beautiful Mermaid library.

使用Beautiful Mermaid库将Mermaid图表渲染为SVG和PNG图像。

Dependencies

依赖项

This skill requires the

agent-browser

skill for PNG rendering. Load it before proceeding with PNG capture.

此技能需要

agent-browser

技能来实现PNG渲染。在进行PNG捕获前请先加载该技能。

Supported Diagram Types

支持的图表类型

Flowchart - Process flows, decision trees, CI/CD pipelines
Sequence - API calls, OAuth flows, database transactions
State - State machines, connection lifecycles
Class - UML class diagrams, design patterns
Entity-Relationship - Database schemas, data models

流程图 - 流程流转、决策树、CI/CD流水线
时序图 - API调用、OAuth流程、数据库事务
状态图 - 状态机、连接生命周期
类图 - UML类图、设计模式
实体关系图 - 数据库架构、数据模型

Available Themes

可用主题

Default, Dracula, Solarized, Zinc Dark, Tokyo Night, Tokyo Night Storm, Tokyo Night Light, Catppuccin Latte, Nord, Nord Light, GitHub Dark, GitHub Light, One Dark.

If no theme is specified, use

default

默认、Dracula、Solarized、Zinc Dark、Tokyo Night、Tokyo Night Storm、Tokyo Night Light、Catppuccin Latte、Nord、Nord Light、GitHub Dark、GitHub Light、One Dark。

如果未指定主题，则使用

default

。

Common Syntax Patterns

常见语法模式

Flowchart Edge Labels

流程图边缘标签

Use pipe syntax for edge labels:

mermaid

A -->|label| B
A ---|label| B

Avoid space-dash syntax which can cause incomplete renders:

mermaid

A -- label --> B   # May cause issues

使用竖线语法添加边缘标签：

mermaid

A -->|label| B
A ---|label| B

避免使用空格-短横线语法，这可能导致渲染不完整：

mermaid

A -- label --> B   # 可能会出现问题

Node Labels with Special Characters

包含特殊字符的节点标签

Wrap labels containing special characters in quotes:

mermaid

A["Label with (parens)"]
B["Label with / slash"]

将包含特殊字符的标签用引号包裹：

mermaid

A["Label with (parens)"]
B["Label with / slash"]

Workflow

工作流程

Step 1: Generate or Validate Mermaid Code

步骤1：生成或验证Mermaid代码

If the user provides a description rather than code, generate valid Mermaid syntax. Consult

references/mermaid-syntax.md

for full syntax details.

如果用户提供的是描述而非代码，请生成有效的Mermaid语法。完整语法细节请参考

references/mermaid-syntax.md

。

Step 2: Render SVG

步骤2：渲染SVG

Run the rendering script to produce an SVG file:

bash

bun run scripts/render.ts --code "graph TD; A-->B" --output diagram --theme default

Or from a file:

bash

bun run scripts/render.ts --input diagram.mmd --output diagram --theme tokyo-night

Alternative runtimes:

bash

npx tsx scripts/render.ts --code "..." --output diagram
deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..." --output diagram

This produces

<output>.svg

in the current working directory.

运行渲染脚本生成SVG文件：

bash

bun run scripts/render.ts --code "graph TD; A-->B" --output diagram --theme default

或从文件读取：

bash

bun run scripts/render.ts --input diagram.mmd --output diagram --theme tokyo-night

其他运行时选项：

bash

npx tsx scripts/render.ts --code "..." --output diagram
deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..." --output diagram

这会在当前工作目录生成

<output>.svg

文件。

Step 3: Create HTML Wrapper

步骤3：创建HTML包装器

Run the HTML wrapper script to prepare for screenshot:

bash

bun run scripts/create-html.ts --svg diagram.svg --output diagram.html

This creates a minimal HTML file that displays the SVG with proper padding and background.

运行HTML包装器脚本为截图做准备：

bash

bun run scripts/create-html.ts --svg diagram.svg --output diagram.html

这会创建一个极简HTML文件，以合适的内边距和背景显示SVG。

Step 4: Capture High-Resolution PNG with agent-browser

步骤4：使用agent-browser捕获高分辨率PNG

Use the agent-browser CLI to capture a high-quality screenshot. Refer to the

agent-browser

skill for full CLI documentation.

bash

undefined

使用agent-browser CLI捕获高质量截图。完整CLI文档请参考

agent-browser

技能。

bash

undefined

Set 4K viewport for high-resolution capture

设置4K视口以实现高分辨率捕获

agent-browser set viewport 3840 2160

Open the HTML wrapper

打开HTML包装器

agent-browser open "file://$(pwd)/diagram.html"

Wait for render to complete

等待渲染完成

agent-browser wait 1000

Capture full-page screenshot

捕获全页截图

agent-browser screenshot --full diagram.png

Close browser

关闭浏览器

agent-browser close


For even higher resolution on complex diagrams, increase the viewport further or use the `--padding` option when creating the HTML wrapper to give the diagram more space.

agent-browser close


对于更复杂的图表，要获得更高分辨率，可以进一步增大视口，或在创建HTML包装器时使用`--padding`选项为图表预留更多空间。

Step 5: Clean Up Intermediary Files

步骤5：清理中间文件

After rendering, remove all intermediary files. Only the final

.svg

and

.png

should remain.

Files to clean up:

The HTML wrapper file (e.g.,
```
diagram.html
```
)
Any temporary
```
.mmd
```
files created to hold diagram code
Any other files created during the rendering process

bash

rm diagram.html

If a temporary

.mmd

file was created, remove it as well.

渲染完成后，删除所有中间文件。仅保留最终的

.svg

和

.png

文件。

需要清理的文件：

HTML包装器文件（例如
```
diagram.html
```
）
为存储图表代码创建的临时
```
.mmd
```
文件
渲染过程中生成的其他文件

bash

rm diagram.html

如果创建了临时

.mmd

文件，也请将其删除。

Output

输出

Both outputs are always produced:

SVG: Vector format, infinitely scalable, small file size
PNG: High-resolution raster, captured at 4K (3840×2160) viewport with minimum 1200px diagram width

Files are saved to the current working directory unless the user explicitly specifies a different path.

始终会生成两种输出：

SVG：矢量格式，可无限缩放，文件体积小
PNG：高分辨率栅格图，以4K（3840×2160）视口捕获，图表宽度最小为1200px

文件会保存到当前工作目录，除非用户明确指定其他路径。

Theme Selection Guide

主题选择指南

Theme	Background	Best For
default	Light grey	General use
dracula	Dark purple	Dark mode preference
tokyo-night	Dark blue	Modern dark aesthetic
tokyo-night-storm	Darker blue	Higher contrast
nord	Dark arctic	Muted, calm visuals
nord-light	Light arctic	Light mode with soft tones
github-dark	GitHub dark	Matches GitHub UI
github-light	GitHub light	Matches GitHub UI
catppuccin-latte	Warm light	Soft pastel aesthetic
solarized	Tan/cream	Solarized colour scheme
one-dark	Atom dark	Atom editor aesthetic
zinc-dark	Neutral dark	Minimal, no colour bias

主题	背景	最佳适用场景
default	浅灰色	通用场景
dracula	深紫色	深色模式偏好
tokyo-night	深蓝色	现代深色美学风格
tokyo-night-storm	更深的蓝色	高对比度需求
nord	北极深色	柔和、沉稳的视觉效果
nord-light	北极浅色	柔和色调的浅色模式
github-dark	GitHub深色	匹配GitHub界面
github-light	GitHub浅色	匹配GitHub界面
catppuccin-latte	暖浅色	柔和的粉彩美学风格
solarized	棕褐色/奶油色	Solarized配色方案
one-dark	Atom深色	匹配Atom编辑器风格
zinc-dark	中性深色	极简风格，无色彩偏差

Troubleshooting

故障排除

Theme not applied

主题未生效

Check the render script output for the

bg

and

fg

values, or inspect the SVG's opening tag for

--bg

and

--fg

CSS custom properties.

检查渲染脚本输出中的

bg

和

fg

值，或查看SVG起始标签中的

--bg

和

--fg

CSS自定义属性。

Diagram appears cut off or incomplete

图表显示被截断或不完整

Check edge label syntax — use
```
-->|label|
```
pipe notation, not
```
-- label -->
```
Verify all node IDs are unique
Check for unclosed brackets in node labels

检查边缘标签语法 — 使用
```
-->|label|
```
竖线表示法，而非
```
-- label -->
```
验证所有节点ID都是唯一的
检查节点标签中是否有未闭合的括号

Render produces empty or malformed SVG

渲染生成空的或格式错误的SVG

Validate Mermaid syntax at https://mermaid.live before rendering
Check for special characters that need escaping (wrap in quotes)
Ensure flowchart direction is specified (
```
graph TD
```
,
```
graph LR
```
, etc.)

渲染前先在https://mermaid.live验证Mermaid语法
检查是否有需要转义的特殊字符（用引号包裹）
确保指定了流程图方向（例如
```
graph TD
```
、
```
graph LR
```
等）