md2docx-cli 0.3.7

将 Markdown 转为 Word（.docx），支持饼图/柱状图与可自定义样式映射

md2docx-cli

Markdown → Word（.docx） 命令行工具：支持饼图 / 分组柱状图嵌入，以及 Word 参考模板自定义样式映射。

安装

# PyPI
pip install md2docx-cli

# 开发安装（仓库根目录）
uv sync
uv pip install -e .

# 安装后命令为 md2docx
md2docx -f example.md -o example.docx

# 全局安装（uv）
uv tool install md2docx-cli

系统依赖：Pandoc ≥ 3.0

用法

单文件转换

md2docx -f example.md -o example.docx
md2docx -f example.md -o example.docx --reference my-template.docx
md2docx -f example.md -o example.docx --toc

批量构建

md2docx -c examples/minimal/nav.yaml

按 nav.yaml 配置多章节 Markdown，生成分章 docx 与合并版（见 examples/minimal/nav.yaml）。

CLI 选项

选项	说明
-v, --version	显示版本号
-f, --from	输入 Markdown（单文件模式，与 -o 成对使用）
-o, --output	输出 .docx（单文件模式，与 -f 成对使用）
-c, --config	批量构建配置文件 nav.yaml（与 -f/-o 二选一）
-r, --reference	Word 样式模板（单文件模式；默认使用包内 reference.docx）
--toc	生成目录（单文件模式）
--toc-depth N	目录层级（默认 3，单文件模式）

单文件模式下，图表缓存目录为与 Markdown 同级的 .md2docx/（可加入 .gitignore）。

仓库结构

├── word_workbench/          # 项目核心
│   ├── cli.py               # md2docx 入口
│   ├── builder.py
│   ├── charts.py
│   ├── preprocess.py
│   └── templates/
│       └── reference.docx   # 默认样式模板（随包分发）
├── scripts/                 # 兼容脚本
└── examples/minimal/        # demo

图表语法

饼图（底部图例按占比从小到大从左到右、从上到下排列；每个扇区显示百分比，低于 small_pct 的沿扇区方向外引）：

```pie
title: 费用构成
small_pct: 5
data:
  输入: 50
  输出: 50
```

分组柱状图：

```bar-grouped
title: 两组对比
categories: [甲, 乙]
series:
  系列 1: [3, 5]
  系列 2: [4, 2]
```

自定义样式

编辑 word_workbench/templates/reference.docx（或通过 -r 指定模板），在 Word 「样式」 面板修改 heading 1、Normal 等。

重新生成默认模板：

python -m word_workbench.generate_template

Demo

uv run md2docx -f examples/minimal/md/sample.md -o examples/minimal/dist/sample.docx

或批量：

uv run md2docx -c examples/minimal/nav.yaml