Metadata-Version: 2.4
Name: md2docx-cli
Version: 0.3.7
Summary: 将 Markdown 转为 Word（.docx），支持饼图/柱状图与可自定义样式映射
Requires-Python: >=3.13
Requires-Dist: matplotlib>=3.8
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# md2docx-cli

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

## 安装

```bash
# 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

## 用法

### 单文件转换

```bash
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
```

### 批量构建

```bash
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` 的沿扇区方向外引）：

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

**分组柱状图**：

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

## 自定义样式

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

重新生成默认模板：

```bash
python -m word_workbench.generate_template
```

## Demo

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

或批量：

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