---
name: pandoc-docx
chineseName: Pandoc Word 导出
description: "Use this skill when converting Markdown to Word DOCX with beautiful Chinese Word reference templates, or converting DOCX back to Markdown. Leverages Pandoc with bundled Lua filters for HTML tag recognition, image captions, font color preservation, and inline code styling. Based on Achuan-2/pandoc_docx_template (MIT License)."
version: 1.0.0
tags: [document, pandoc, word, docx, markdown]
---

# Pandoc DOCX Template Skill

> AI 只需写标准 Markdown，排版由参考模板 + Lua 过滤器统一接管。
> 适合内容型文档（笔记、文章、论文、技术文档）。
> 需要像素级控制（证书、合同）请用 officecli-docx。

## Prerequisites

```bash
pandoc --version  # 需要 Pandoc >= 2.19
```

未安装时：
- **Windows**: `winget install JohnMacFarlane.Pandoc`
- **macOS**: `brew install pandoc`
- **Linux**: `apt-get install pandoc`

## Quick Start

### Markdown → DOCX（推荐：两步管线）

```bash
python {base_path}/scripts/md2docx.py input.md -o output.docx
```

默认使用 `templates/template_标题不编号-列表第二行顶格.docx` 模板 + `markdown-to-docx.lua` 聚合过滤器。

### 选择其他模板

```bash
python {base_path}/scripts/md2docx.py input.md -o output.docx \
  --reference "{base_path}/templates/template_标题编号-列表第二行顶格.docx"
```

### 传递额外 Pandoc 参数

```bash
python {base_path}/scripts/md2docx.py input.md -o output.docx \
  -- --highlight-style tango --toc --toc-depth=2
```

### 不用 Python（直接 Pandoc）

```powershell
pandoc input.md -t html | pandoc -f html -o output.docx --reference-doc "{base_path}/templates/template_标题不编号-列表第二行顶格.docx" --lua-filter "{base_path}/markdown-to-docx.lua"
```

### DOCX → Markdown

```bash
python {base_path}/scripts/docx2md.py input.docx -o output.md --media-dir assets
```

或直接：

```bash
pandoc input.docx -t gfm -o output.md --extract-media=./assets --wrap=none
```

## Available Templates

所有模板在 `{base_path}/templates/` 目录：

| 模板文件 | 用途 |
|---------|------|
| `template_标题不编号-列表第二行顶格.docx` | **默认。** 标题不编号，列表换行顶格 |
| `template_标题不编号-列表第二行缩进.docx` | 标题不编号，列表换行缩进 |
| `template_标题编号-列表第二行顶格.docx` | 标题编号，列表换行顶格 |
| `template_标题编号-列表第二行缩进.docx` | 标题编号，列表换行缩进 |
| `template_标题不编号-列表第二行顶格-无首行缩进.docx` | 标题不编号，无首行缩进 |
| `template_sci论文-标题编号.docx` | SCI 论文样式（标题编号） |
| `template_sci论文-标题不编号.docx` | SCI 论文样式（标题不编号） |

**选择规则**：
- 日常笔记/文章 → `template_标题不编号-列表第二行顶格.docx`（默认）
- 正式报告/公文 → `template_标题编号-列表第二行顶格.docx`
- 学术论文 → `template_sci论文-标题编号.docx`
- 简洁文档 → `template_标题不编号-列表第二行顶格-无首行缩进.docx`

## Lua Filters

聚合过滤器 `{base_path}/markdown-to-docx.lua` 自动加载以下子过滤器：

| 过滤器 | 功能 |
|-------|------|
| `lua/preserve_font_color.lua` | 保留 `<span style="color:red">` 字体颜色 |
| `lua/image-title-to-caption.lua` | 用图片 title（非 alt）作为 Word 图注 |
| `lua/add-inline-code.lua` | 为行内代码添加自定义 `Inline Code` 样式 |

按需加载的额外过滤器：
- `lua/image-title-to-caption-add-number.lua` — 图片编号（图 1：...）
- `lua/markdown-html-recognition.lua` — 识别 `<sub>/<sup>/<u>/<img>` 和 `==高亮==` 语法

使用单独过滤器：

```bash
pandoc input.md -t html | pandoc -f html -o output.docx \
  --reference-doc "{base_path}/templates/template_标题不编号-列表第二行顶格.docx" \
  --lua-filter "{base_path}/lua/preserve_font_color.lua" \
  --lua-filter "{base_path}/lua/image-title-to-caption-add-number.lua"
```

## How It Works

Markdown → DOCX 使用**两步管线**：

```
Markdown → (Pandoc) → HTML → (Pandoc + Lua filters + template) → DOCX
```

先转 HTML 再转 DOCX，比直接 Markdown→DOCX 保留更多格式（特别是 HTML 标签），Lua 过滤器在第二步处理特殊元素。

## AI Best Practices

生成 Markdown 时注意：
1. 使用标准 Markdown 语法（标题、段落、列表、代码块、表格）
2. 图片用 `![alt](url "title")` — title 会成为 Word 图注
3. 颜色用 `<span style="color:red">text</span>`
4. 上下标用 `<sub>sub</sub>` / `<sup>sup</sup>`（需加载 markdown-html-recognition.lua）
5. 高亮用 `==text==`（需加载 markdown-html-recognition.lua）
6. 行内代码会自动应用 `Inline Code` 样式

## Validation

转换后：
1. 确认输出文件存在
2. 检查 Pandoc stderr 有无过滤器/模板错误
3. 正式文档在 Microsoft Word 中检查（模板在 Windows Office 上测试）

## 与 officecli-docx 的关系

| 维度 | pandoc-docx（本技能） | officecli-docx |
|------|:---:|:---:|
| AI 参与度 | 低 — 只写 Markdown | 高 — 逐条写命令 |
| 出错率 | 极低 | 中等 |
| 排版精美度 | 高（模板统一控制） | 极高（像素级控制） |
| 适合场景 | 内容型（文章/笔记/论文） | 数据型（证书/合同/报告） |

**路由规则**：
- 用户说"导出 Word" + 内容是文章/笔记 → 用本技能
- 用户说"生成证书/合同" + 需要精确字段 → 用 officecli-docx
- 不确定 → 先试本技能

## Attribution

Templates and Lua filters based on [Achuan-2/pandoc_docx_template](https://github.com/Achuan-2/pandoc_docx_template) (MIT License).