DOCX Pipeline 是个把 Markdown 转成中文 DOCX 的命令行工具。双后端：Pure Python 零外部依赖，Pandoc 质量更高。v1.2.0 补上了纯 Python 后端对 LaTeX 数学公式的支持，写论文、出报告时不用硬装 Pandoc。

下面先说怎么用，再简单提实现。

安装

Python 3.10 以上：

pip install git+https://github.com/redamancy231-create/docx-pipeline.git

核心依赖会一起装好：python-docx、PyYAML、click、Pillow。Pandoc 和 mermaid-cli 是可选的，后面按需安装。

一分钟上手

1. 初始化项目

docx-pipeline init --project-dir ./my-doc --template report --name "技术报告"

执行完会在 ./my-doc 下生成 project.yaml，里面包含页面、字体、路径、后端开关等所有配置。

四个内置模板：

模板 场景 默认后端
default 通用中文文档 Pure Python
academic 论文/学位论文 Pure Python
report 技术报告，带目录和 Mermaid Pandoc
strategy 量化策略文档 Pure Python

2. 写 Markdown

模板会给你一个入口文件路径，默认在 ./md/main.md。直接写普通 Markdown 就行，公式用 $...$ 行内、$$...$$ 独立：

---
title: 示例报告
---

# 正文

考虑正弦信号的采样定理：

$$f_s \geq 2 f_{\max}$$

若采样率 $f_s = 100\,\text{Hz}$，则奈奎斯特频率为 $f_N = f_s/2 = 50\,\text{Hz}$。

## 表格

| 参数 | 值 |
|------|-----|
| 采样间隔 | 0.01 s |
| 窗长 | 21 |

3. 转换

cd ./my-doc
docx-pipeline convert --config ./project.yaml

输出路径由 project.yaml 里的 paths.docx_output 决定，默认 ./output/doc.docx。

想换输出文件：

docx-pipeline convert --config ./project.yaml --output ./out/报告.docx

只想看会不会报错，不生成文件：

docx-pipeline convert --config ./project.yaml --dry-run

常用命令

# 查看配置摘要
docx-pipeline info --config ./project.yaml

# 校验配置合法性
docx-pipeline validate --config ./project.yaml

# 强制用 Pure Python 后端
docx-pipeline convert --config ./project.yaml --method pure

# 强制用 Pandoc 后端
docx-pipeline convert --config ./project.yaml --method pandoc

# 传额外参数给 pandoc
docx-pipeline convert --config ./project.yaml --pandoc-args "--number-sections"

init 和 convert 是日常使用最多的两个命令。

配置重点

project.yaml 是全部行为的入口。几个常见调整：

改输入输出路径

paths:
  md_source: "./chapters/main.md"
  docx_output: "./output/报告.docx"

改字体

fonts:
  east_asian: "微软雅黑"
  latin: "Times New Roman"

字体必须在系统里已安装，否则 Word 会回退默认字体。

页面和缩进

page:
  size: "A4"
  orientation: "portrait"
  margins:
    top: 2.54
    bottom: 2.54
    left: 3.18
    right: 3.18

styles:
  paragraph:
    line_spacing: 1.15
    first_line_indent: 0.0   # cm，学术论文可设 0.74 左右

后端开关

pandoc:
  enabled: false          # true 启用 Pandoc
  extra_args: []
  reference_docx: ""      # Pandoc 参考文档路径

enabled: false 时走 Pure Python，LaTeX 公式由 v1.2.0 新增的 latex2mathml → MathML → OMML 桥转换。enabled: true 时走 Pandoc，公式渲染质量更好，但需要系统里有 pandoc。

后端怎么选

  • 不想装 pandoc → Pure Python，一个 Python 环境就够了，公式也能转。
  • 要代码语法高亮、复杂表格、章节自动编号 → Pandoc。
  • 想精确控制中文字体、缩进、行距 → Pure Python 更直接。

Auto 模式（默认）会先看 pandoc.enabled，再看 pandoc 是否在 PATH 里，能 pandoc 就 pandoc，不能就自动降级到 Pure Python。

Mermaid 图表

report 模板默认开启 Mermaid。需要 Node.js 和 mermaid-cli：

npm install -g @mermaid-js/mermaid-cli

Markdown 里写：

```mermaid
flowchart LR
    A[输入] --> B[处理] --> C[输出]
```

转换时会自动渲染成 PNG 嵌入 DOCX。渲染失败的代码块会保留原文并加警告注释。

v1.2.0 公式实现简说

纯 Python 后端新增了一条 LaTeX → Word 原生公式的路径：

  1. 扫描 Markdown，把 $...$ 和 $$...$$ 抠出来，替换成占位符。
  2. 用 latex2mathml 把 LaTeX 转成 MathML。
  3. 用 lxml 遍历 MathML 树，生成 Word 的 m:oMath / m:oMathPara。
  4. 行内公式挂到段落里，独立公式包成居中段落。
  5. 转换失败就回退成原始 LaTeX 文本，不会让整个文档崩掉。

覆盖分数、根号、上下标、极限、n 元运算符、重音、矩阵、括号、围栏等 14 种结构，有 21 个自动化用例校验。

不过说实话，Pure Python 的 OMML 渲染在分式、根号、大型运算符等复杂式子上还是有缺陷；Pandoc 后端十五年打磨的 TeX 引擎更稳。所以能装 pandoc 的话，复杂公式建议优先 Pandoc 后端。

两个容易踩的坑

Windows 乱码

中文输出在 Windows 下可能乱码，加环境变量：

export PYTHONIOENCODING=utf-8

PowerShell：

$env:PYTHONIOENCODING = "utf-8"

目录重复

如果 Markdown 里已经手写了一个”目录”章节，pipeline 又会自动插入 Word 的 TOC 域，结果出现双目录。要么在 Markdown 里删掉手工目录，要么在 project.yaml 里设 styles.toc.enabled: false。

一句话总结

DOCX Pipeline 让 Markdown → Word 这件事可以一条命令跑完；v1.2.0 之后，公式也不需要 Pandoc 了。写报告、论文、技术文档时，它能省下大量调格式的时间。