kevinswiber/mmdflux
GitHub: kevinswiber/mmdflux
一个用 Rust 实现的 Mermaid 图表渲染工具，输出终端文本、SVG 与结构化 MMDS JSON，面向自动化与工具链集成。
Stars: 45 | Forks: 2
# mmdflux
[](https://crates.io/crates/mmdflux)
[](https://docs.rs/mmdflux)
[](https://github.com/kevinswiber/mmdflux/actions/workflows/ci.yml)
将 Mermaid 图表渲染为终端文本、SVG 和结构化 JSON。
mmdflux 是一个用 Rust 构建的图表渲染工具包。它以 CLI、Rust 库和 WebAssembly 包的形式发布——所有这些都来自同一个代码库。
它包含自己的图形布局引擎（具有本地正交路由）、用于终端输出的字符网格渲染器，以及
[MMDS](docs/mmds.md) —— 一种为工具、适配器和 LLM/代理流水线设计的结构化 JSON 格式。
[Playground](https://play.mmdflux.com) · [Releases](https://github.com/kevinswiber/mmdflux/releases) · [Gallery](docs/gallery.md) · [MMDS Spec](docs/mmds.md)
## 一瞥
一个 Mermaid 源文件，多个输出：终端文本、SVG 和机器可读的 JSON。
**Mermaid 源文件** ([`docs/assets/readme/at-a-glance.mmd`](docs/assets/readme/at-a-glance.mmd))
```
graph TD
subgraph sg1[Horizontal Section]
direction LR
A[Step 1] --> B[Step 2] --> C[Step 3]
end
Start --> A
C --> End
```
**SVG 输出** (`mmdflux --format svg --layout-engine flux-layered --curve linear-rounded ...`)
**文本输出** (`mmdflux --format text ...`)
```
┌───────┐
│ Start │
└───────┘
│
┌───┘
│
│
│
│
│
┌───────┼ Horizontal Section ────────┐
│ ▼ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Step 1 │─►│ Step 2 │─►│ Step 3 │ │
│ └────────┘ └────────┘ └────────┘ │
│ ┌────┘ │
└─────────────────────┼──────────────┘
│
│
│
│
┌──────┘
│
▼
┌─────┐
│ End │
└─────┘
```
**MMDS JSON 输出**: [`docs/assets/readme/at-a-glance.mmds.json`](docs/assets/readme/at-a-glance.mmds.json)
## 为何选择 mmdflux
**无运行时依赖。** 一个单独编译的二进制文件。不需要 Node.js、无需无头浏览器、无需 Puppeteer。
**终端文本是首等输出。** 文本渲染不是次要模式——它拥有自己的网格布局系统、正交边路由，以及专为终端可读性设计的 Unicode 框线字符。
**原生正交路由。** `flux-layered` 引擎将布局和路由视为一个统一的求解契约。边遵循直角路径，具有确定性的扇入/扇出策略和形状感知的附着点——解决了 Mermaid 渲染中最常见的抱怨之一。
**面向工具与代理的结构化 JSON。** MMDS（Machine-Mediated Diagram Specification）输出定位后的图形数据——节点坐标、路由边路径、子图边界——以便下游工具无需解析 SVG 或抓取像素即可消费图形几何信息。
**复合图形布局。** 子图作为单一复合图形的一部分进行布局，而不是递归渲染。这能产生全局优化的定位和一致的跨边界边路由。
**支持多种图形引擎。** 默认的 `flux-layered` 引擎处理流程图/类图/状态图的文本、SVG 和 MMDS 输出。可切换到 `mermaid-layered` 以获得与 Mermaid 兼容的图形输出。
## 生态系统
| 包 | 描述 |
| --- | --- |
| [`mmdflux`](https://crates.io/crates/mmdflux) | CLI 和 Rust 库（crates.io） |
| [`@mmds/wasm`](https://www.npmjs.com/package/@mmds/wasm) | WebAssembly 绑定（npm） |
| [`@mmds/core`](https://www.npmjs.com/package/@mmds/core) | MMDS 规范化、遍历和验证工具（npm） |
| [`@mmds/excalidraw`](https://www.npmjs.com/package/@mmds/excalidraw) | MMDS 转 Excalidraw `.excalidraw` JSON（npm） |
| [`@mmds/tldraw`](https://www.npmjs.com/package/@mmds/tldraw) | MMDS 转 tldraw `.tldr` JSON（npm） |
| [Playground](https://play.mmdflux.com) | 交互式浏览器编辑器（由 WASM 驱动） |
## 安装
### Homebrew（推荐）
```
brew tap kevinswiber/mmdflux
brew install mmdflux
```
### Cargo
```
cargo install mmdflux
```
### 预编译二进制文件
从 [GitHub Releases](https://github.com/kevinswiber/mmdflux/releases) 下载平台二进制文件。
## 快速开始
```
# 将 Mermaid 文件渲染为文本（默认格式）
mmdflux diagram.mmd
# 从标准输入读取 Mermaid
printf 'graph LR\nA-->B\n' | mmdflux
# 禁用文本/ASCII 输出的 ANSI 颜色
NO_COLOR=1 mmdflux --format text diagram.mmd
# 覆盖单次调用的 NO_COLOR
NO_COLOR=1 mmdflux --format text --color always diagram.mmd
# SVG 输出
mmdflux --format svg diagram.mmd -o diagram.svg
# 带命名主题的 SVG 输出
mmdflux --format svg --svg-theme dark diagram.mmd -o diagram.svg
# 带终端感知浅色/深色主题选择的 SVG 输出
mmdflux --format svg --svg-theme-auto diagram.mmd -o diagram.svg
# 使用 CSS 变量和十六进制备用方案的面向浏览器的 SVG
mmdflux --format svg --svg-theme dark --svg-theme-mode dynamic diagram.mmd -o diagram.svg
# 带路由几何细节的 MMDS JSON 输出
mmdflux --format mmds --geometry-level routed diagram.mmd
# 校验模式（验证输入并打印诊断信息）
mmdflux --lint diagram.mmd
```
启用 ANSI 后，文本/ASCII 输出会将 Mermaid 样式映射到终端颜色（当存在明确对应时）：节点 `style`/`classDef` 的 `fill`、`stroke` 和 `color` 控制节点背景、边框和标签颜色；流程图的 `linkStyle ... stroke:` 控制边和箭头的前景色；SVG 专属属性（如 `stroke-width` 和 `stroke-dasharray`）在文本/ASCII 输出中作为无操作保留。
更多示例请参见以下章节。
## 支持的功能
- **图表类型：** 流程图、类图、时序图、状态图
- **输出格式：** Unicode 文本、ASCII 文本、SVG、MMDS JSON
- **布局方向：** `TD`、`BT`、`LR`、`RL`（支持每个子图覆盖）
- **边样式：** 实线、虚线、加粗线、不可见线、十字箭头、圆形箭头
- **路由：** 正交、多折线、直接（支持曲线选项：basis、linear、linear-rounded、linear-sharp）
- **往返转换：** Mermaid 与 MMDS 之间互相转换
## 图形引擎家族
| | `flux-layered` | `mermaid-layered` |
| --- | --- | --- |
| 适用范围 | 流程图/类图/状态图文本、SVG、MMDS | 流程图/类图 SVG、MMDS |
| 路由 | 正交、多折线、直接 | 多折线 |
| 子图 | 复合图形（全局布局） | 复合图形 |
| 适用场景 | 确定性路由输出 | 与 Mermaid 兼容的输出 |
时序图使用单独的时间线渲染器，支持文本/ASCII、SVG 和 MMDS 输出，且不接受 `--layout-engine` 参数。
### SVG 边预设
| 预设 | 路由 | 曲线 |
| --- | --- | --- |
| `smooth-step`（默认） | 正交 | 圆角弧线 |
| `curved-step` | 正交 | Basis 样条 |
| `step` | 正交 | 锐角拐点 |
| `polyline` | 多折线 | 锐角拐点 |
| `straight` | 直接 | 锐角拐点 |
```
# 正交拐角平滑（默认）
mmdflux --format svg diagram.mmd -o diagram.svg
# 正交基路径曲线
mmdflux --format svg --edge-preset curved-step diagram.mmd -o diagram.svg
# 显式曲线控制
mmdflux --format svg --curve linear-rounded diagram.mmd -o diagram.svg
```
## SVG 主题
SVG 主题是可选用的，仅影响 SVG 输出。
- **显式配置优先。** CLI 标志和 `RenderConfig.svg_theme` 优先于 Mermaid 源文件提示。
- **自动主题是显式的。** `--svg-theme-auto` 在渲染前解析为具体命名主题，因此启用自动主题时 Mermaid 源文件提示会被抑制。
- **支持 Mermaid 提示。** YAML 前言中的 `config.theme` 和 `%%{init: {"theme": "..."}}%%` 都会在未提供显式 SVG 主题时选择一个命名 SVG 主题。
- **无主题输出仍可用。** 如果没有显式主题或 Mermaid 提示，SVG 渲染将保留现有的无主题调色板。
- **静态模式是默认值。** 静态模式输出具体的十六进制颜色，以获得最大栅格器兼容性。
- **动态模式是附加的。** `--svg-theme-mode dynamic` 输出相同的十六进制回退值，并附加根 CSS 变量和 `