SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场markdown-to-word-mermaid

markdown-to-word-mermaid

办公与效率

查看项目

更新于 10-27 09:47

技能介绍

用途

该技能用于将包含 Mermaid 代码块的 Markdown 文档导出为 Word（.docx），并嵌入 SVG 图表及 3x PNG 备用图。适用于以下场景：设计文档、运行手册或报告包含 Mermaid 代码块且必须以 DOCX 交付；图表标签在缩放或打印时必须保持清晰；高图表需要页面感知放置，而不是被拆分到多页。

如果只是进行常规 Markdown 到 DOCX 转换且已有 PNG 图片，使用 md-to-docx 等通用转换器可能更简单。本技能专注于 Mermaid 图表的渲染与打包。SVG 嵌入不会创建可编辑的 Word 形状、连接线或文本框。

主要能力

  • 将 Markdown 中的标题、段落、强调、列表（保留有序列表起始编号和独立列表边界）、块引用、表格和代码块转换为 Word 内容。
  • 每个 Mermaid 代码块渲染为 SVG 和 3x PNG，每条命令有超时限制（默认 120 秒）。
  • Office SVG 扩展引用 SVG；普通图像引用保留 PNG 回退；绘图元数据（title 和 descr）包含章节标题或 Mermaid 的 accTitle/accDescr 以及图表类型。
  • 输出 DOCX 文件在临时目录中暂存并注入 SVG，然后移动到目标路径，因此失败的运行不会留下部分文件。
  • 所选字体应用于 Word 段落样式和 Mermaid 字体配置。代码运行使用 Consolas。字体不嵌入；不可用字体可能被替换。
  • 全局及流程图设置 htmlLabels: false，以避免 Office 可能无法显示的 HTML foreignObject 标签。需检查实际 SVG 输出中是否存在不支持的构造。
  • 图表居中、保持宽高比，并使用不拆分的段落。占据页面正文高度至少 70% 的图表从新页开始。过大的图表缩放至页面正文高度。大型图表会生成可读性警告。
  • 简单的单行 frontmatter 标题成为文档标题；其他 frontmatter 字段从正文中移除。这不是完整的 YAML 元数据解析器。
  • 普通 Markdown 图像链接保留为 alt 文本和源路径或 URL；它们不会被嵌入。原始 HTML 被缩减为文本，不会执行。

使用方式

环境要求

  • Python 3.10+ 以及 scripts/requirements.txt 中的包。
  • 与所选 Mermaid CLI 版本兼容的 Node.js，以及 @mermaid-js/mermaid-cli。
  • Puppeteer 可用的本地浏览器，以及覆盖文档字符的已安装字体。
  • 默认字体：Noto Sans JP。使用 --font-family 选择其他已安装字体。

路径应相对于本技能的安装目录解析，而不是假定的仓库名称。以下示例从技能目录运行。使用用户选择的 Python 环境（python、python3 或其绝对路径）。

安装依赖前，确认环境并在需要时获得许可。如果已有 Mermaid CLI 则复用。否则安装到用户批准的本地工具目录，而非全局：

python -m pip install -r scripts/requirements.txt
npm install --prefix ./run/mermaid-cli @mermaid-js/mermaid-cli

本地可执行文件在 POSIX 上为 ./run/mermaid-cli/node_modules/.bin/mmdc，在 Windows 上为 ./run/mermaid-cli/node_modules/.bin/mmdc.cmd。将已安装依赖排除在提交的技能包之外。在消费项目中锁定所选依赖版本以实现可重现安装。

在 Windows 上，转换器检测标准 Chrome 和 Edge 路径。对于其他浏览器位置，将 MERMAID_BROWSER_PATH 设置为其绝对可执行路径：

$env:MERMAID_BROWSER_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"

在 POSIX 上，使用 export MERMAID_BROWSER_PATH=/absolute/path/to/browser，或使用 Puppeteer 安装的浏览器。不要仅为使转换通过而禁用浏览器沙箱。

工作流程

  1. 确认输入 Markdown 文件、输出目标和字体。如果未提供目标，使用输入路径加 .docx 扩展名。
  2. 检查输出是否已存在。绝不删除或覆盖现有文档；要求不同的目标。
  3. 运行 scripts/markdown_to_word.py。保留用户的图表源和含义。不要静默修复无效的 Mermaid。
  4. 检查生成的包，并在 Word 可用时目视检查文档。分别报告包检查和目视检查。

使用 PATH 中的 mmdc：

python scripts/markdown_to_word.py input.md --output output.docx

在 Windows 上使用工作区本地 CLI：

python scripts/markdown_to_word.py input.md --output output.docx --mermaid-cli ./run/mermaid-cli/node_modules/.bin/mmdc.cmd

选择已安装字体：

python scripts/markdown_to_word.py input.md --output output.docx --font-family "Noto Sans JP" --timeout 120

可重现示例：将 assets/example.md 转换为新的输出路径。它包含英文和日文标签、多个图表以及一个高图表。

适用场景

  • 设计文档、运行手册或报告包含 Mermaid 代码块且必须以 DOCX 交付。
  • 图表标签在缩放或打印时必须保持清晰。
  • 高图表需要页面感知放置，而不是被拆分到多页。

限制

  • 缺少输入、扩展名错误、输出已存在、缺少 CLI、无效 Mermaid、渲染失败或不可用的 SVG 尺寸都会以错误停止转换。
  • 转换器不调用外部渲染服务或单独的 AI API。依赖安装和浏览器执行不是离线沙箱。渲染前审查不受信任的图表内容，包括外部资源。
  • 图表不是语义可编辑的 Office 对象。Word 渲染、字体替换和最终分页取决于查看器，必须在其中检查。
  • 成功创建 DOCX 并不证明每个图表标签都可读。仅在用户批准的情况下在源中拆分大型图表。
  • 字体不嵌入；不可用字体可能被替换。
  • 普通 Markdown 图像链接不会被嵌入。
  • 原始 HTML 被缩减为文本，不会执行。

验证

从技能目录运行测试套件：

python -m unittest discover -s tests -v

普通套件模拟 Mermaid 渲染。要同时运行真实渲染器测试，将 MERMAID_CLI 设置为 CLI 可执行文件的绝对路径，然后再次运行命令。在 Windows PowerShell 上：

$env:MERMAID_CLI = (Join-Path $env:APPDATA "npm\mmdc.cmd")
python -m unittest discover -s tests -v

该测试渲染捆绑示例并检查生成的 DOCX 的 SVG 引用、PNG 回退、标签和绘图尺寸。它不自动化 Word 目视检查。

报告完成前：

  • 统计 Mermaid 代码块数量，并验证 DOCX 中相同数量的 SVG 部件和 SVG 图像引用。
  • 确认 PNG 回退引用存在，且示例的 SVG 中不残留标签 foreignObject。
  • 在 Word 中检查节点名称、分支标签、字体、图表放置和页面边界；当清晰度重要时检查缩放或打印输出。
  • 如果 Word 或实际渲染器不可用，说明未执行哪些检查。

关于贡献范围、评估案例和草稿提交描述，请参阅 references/publication.md。该文件是维护者指南，不是发布许可。

注意事项

  • mmdc.cmd 需要 Windows 命令处理；通过 --mermaid-cli 传递其路径，而不是重写脚本。
  • 缺少字体可能影响 PNG 渲染和 SVG 显示。使用在渲染和查看机器上都安装的字体系列。
  • 保持 SVG 和 PNG 配对。用截图替换 SVG 会破坏矢量保留工作流。
  • 包验证、渲染器测试、代理选择评估和人工目视验收是不同的检查。