team/team/md-export.md

Markdown 导出 docx/pdf 经验总结

本文档记录使用 Pandoc + Mermaid CLI 将 Markdown 导出为 docx/pdf 过程中遇到的问题和解决方案。

---

1. 工具链依赖

工具	用途	安装方式
pandoc	Markdown → docx/pdf 转换	sudo apt install -y pandoc
mmdc	Mermaid 图表渲染为 PNG	npm install -g @mermaid-js/mermaid-cli
xelatex	PDF 引擎（支持中文）	sudo apt install -y texlive-xetex
Noto Sans CJK SC	PDF 中文字体	sudo apt install -y fonts-noto-cjk

2. 导出流程

项目使用 scripts/md_export.py 脚本，流程为：

1. 扫描 Markdown 中的 ```mermaid ``` 代码块
2. 用 mmdc 将每个 Mermaid 代码块渲染为 PNG，同时保留 .mmd 源文件
3. 将 Markdown 中的 Mermaid 代码块替换为 ![](images/xxx.png) 图片引用
4. 将替换后的临时 Markdown 通过 pandoc 导出为目标格式
5. 清理临时文件

用法：

uv run python scripts/md_export.py docs/文件.md --format docx
uv run python scripts/md_export.py docs/文件.md --format pdf

3. Mermaid 图表处理

3.1 Mermaid 代码块替换策略

• 正则匹配：r"```mermaid\n(.*?)\n```"（re.DOTALL 模式）
• 命名规则：{文件名}-mermaid-{序号}.png，如 建模论文-mermaid-1.png
• 图片存放：与 Markdown 同级的 images/ 子目录
• 同时保留 .mmd 源文件：便于后续手动重新渲染

3.2 mmdc 渲染参数

mmdc -i input.mmd -o output.png -b white

• -b white：白色背景，避免透明背景在 docx/pdf 中显示异常
• mmdc 需要 Puppeteer（Chromium），首次运行会自动下载

3.3 Mermaid 语法兼容性

详见 team/mermaid.md，要点：

• erDiagram 避免使用保留字（Class、Note、End）
• 字段类型不加引号
• 不同渲染器（GitHub / VS Code / mmdc CLI）行为可能略有差异

4. Pandoc PDF 导出（中文支持）

4.1 必须使用 XeLaTeX

pandoc input.md -o output.pdf --pdf-engine=xelatex \
  -V CJKmainfont=Noto Sans CJK SC \
  -V geometry:margin=2.5cm

• --pdf-engine=xelatex：XeLaTeX 原生支持 Unicode 和中文
• -V CJKmainfont=Noto Sans CJK SC：指定中文字体
• -V geometry:margin=2.5cm：合理页边距

不要使用默认的 pdflatex，它不支持中文。

4.2 特殊字符缺失警告

[WARNING] Missing character: There is no ≈ (U+2248) in font [lmroman10-regular]

原因：数学符号（如 ≈）在 Latin Modern Roman 字体中不存在。

解决方案（按推荐程度排序）：

1. 改用 LaTeX 公式：将 ≈ 替换为 $\approx$，由 MathJax/LaTeX 引擎渲染
2. 指定额外字体：在 pandoc 参数中添加备用字体覆盖全范围
3. 忽略：不影响整体排版，仅个别字符显示为空白

4.3 资源路径

--resource-path /path/to/markdown/parent

pandoc 查找图片时使用此路径。脚本中设为 Markdown 文件所在目录，确保 ![](images/xxx.png) 相对路径能正确解析。

5. Pandoc DOCX 导出

docx 导出相对简单，无需额外字体配置：

pandoc input.md -o output.docx --resource-path /path/to/markdown/parent

docx 格式本身支持 Unicode，不会出现字符缺失问题。

6. 临时文件处理

脚本将替换 Mermaid 后的 Markdown 写入同目录临时文件，原因是：

• pandoc 的 --resource-path 基于输入文件位置解析相对路径
• 如果临时文件在 /tmp/ 等其他目录，images/xxx.png 路径将无法找到
• 导出完成后（无论成功或失败）自动删除临时文件（try/finally）

7. 常见问题排查

问题	原因	解决
mmdc: command not found	未安装 mermaid-cli	npm install -g @mermaid-js/mermaid-cli
pandoc: command not found	未安装 pandoc	sudo apt install -y pandoc
PDF 中文乱码/缺失	未使用 XeLaTeX 或未指定中文字体	加 --pdf-engine=xelatex -V CJKmainfont=...
≈ 等符号在 PDF 中空白	Latin Modern 字体不含该字符	改用 $\approx$ 等 LaTeX 公式
Mermaid 图表不显示	mmdc 渲染失败或图片路径错误	检查 .mmd 源文件语法，确认 images/ 目录
图片路径找不到	临时文件与图片不在同一目录树	确保 --resource-path 和临时文件位置正确
python: 未找到命令	系统 python 命令未注册	使用 uv run python 替代

8. 与 Markdown Preview Enhanced 的关系

Markdown Preview Enhanced (MPE) 是 VS Code 插件，可实时预览 Mermaid 图表。本项目的导出流程独立于 MPE：

• MPE：开发时预览用，支持 Mermaid 实时渲染
• md_export.py：最终导出用，通过 mmdc CLI 渲染 Mermaid 后由 pandoc 转换

两者使用相同的 Mermaid 语法，但渲染器版本可能不同。如果 MPE 预览正常但导出异常，优先检查 mmdc 版本。