技能介绍

告别手写 Mermaid 的重复劳动

在编写技术设计文档时，我们经常需要在 Markdown 中插入流程图。为了图示的美观与可维护性，Mermaid 几乎成了首选方案。然而，直接手写 Mermaid 语法不仅繁琐，且在需求频繁变更时极难维护。很多开发者习惯先用 ASCII 字符在纯文本中快速勾勒出流程骨架，但到了最终排版阶段，面对这些由 ↓、├── 和 [节点] 组成的粗糙图形，将其手动重绘为标准的 Mermaid 代码就成了一项耗时且容易出错的苦差事。

核心能力与转换机制

md2html 技能专为解决这一痛点而生。它能够扫描 Markdown 文档，精准识别四种常见的 ASCII 流程图写法，并将其自动重写为标准的 Mermaid flowchart 语法：

括号式流程：如 [线索进来] 配合箭头连接。
编号式流程：如 01 启动流程 配合 ↓ 串联步骤。
业务域流程：包含“域：”标识的层级业务流转。
带分支的序列流程：使用 ↓ 向下延伸，并结合 ├── 和 └── 表达逻辑分支。

在处理过程中，该工具遵循非侵入原则：仅对未标记语言的纯文本代码块进行转换，将其原地替换为带有 mermaid 标识的代码块，已转换的代码不会被重复处理。此外，它不仅支持输出更新后的 Markdown 文件，还能直接渲染生成包含 Mermaid.js 渲染引擎的独立 HTML 页面，支持自定义页面标题与图表主题。

适用边界与工程建议

虽然自动化转换能大幅降低图表绘制成本，但在工程实践中仍需注意其边界。该工具遵循范围最小化原则，当前版本仅聚焦于 ASCII 到 Mermaid 的转换，不涉及其他复杂图表类型的扩展。

避免处理超复杂图形：对于节点数量庞大、嵌套极深的复杂 PlantUML 图表，强行转换可能导致 Mermaid 渲染错乱。建议此类场景直接保留 PlantUML 源码或导出为 PNG 图片嵌入。
离线环境适配：生成的 HTML 默认通过 CDN 引入 Mermaid.js v10。若部署环境无外网，需在生成后手动替换模板中的资源路径为本地依赖。