HanDocx

English

HanDocx 是一个面向中文报告、技术文档和 AI 生成内容的 Markdown 转 Word 工具。它以 Pandoc 作为转换引擎，在其基础上提供可复用 的中文 Word 模板、TOML 配置、图片路径处理、批量转换和环境诊断。

当前版本：0.1.2，处于早期开发阶段。命令行和配置格式会尽量保持精简、稳定。

主要能力

• 生成 A4 页面并分别设置中文、英文字体。
• 内置可分发的 reference.docx，不依赖本机 Word 默认样式。
• 将 LaTeX 数学公式转换为 Word 原生公式对象。
• 自动解析 Markdown 文件和配置目录中的相对图片路径。
• 支持目录、标题编号、代码高亮和 Lua 过滤器。
• 为未指定宽度的 Markdown 表格提供等宽列默认值。
• 批量转换目录树，并保留相对目录结构。
• 提供 doctor 和 --dry-run，便于检查环境和排查问题。
• Python 运行时零第三方依赖，转换时只需要 Pandoc。

环境要求

• Python 3.11 或更高版本。
• Pandoc 3.x，已加入 PATH，或者通过 --pandoc 指定路径。
• Microsoft Word 或 WPS 不是必需项，但建议用于最终排版检查。

安装

从 GitHub 克隆并安装：

git clone https://github.com/waterep9/handocx.git
cd handocx
python -m pip install -e .
handocx doctor

如果 doctor 提示找不到 Pandoc，请从 Pandoc 安装页面下载安装。

快速开始

创建一个包含配置文件、可编辑 Word 模板和示例 Markdown 的项目：

handocx init my-report
cd my-report
handocx convert report.md

直接使用内置模板转换：

handocx convert examples/report.md -o dist/report.docx

只查看即将执行的 Pandoc 命令：

handocx convert examples/report.md --dry-run

批量转换目录中的 Markdown：

handocx batch "docs/**/*.md" --output-dir dist

配置

HanDocx 默认读取当前目录中的 handocx.toml。也可以通过 --config 指定 其他配置文件。文件中的相对路径以配置文件所在目录为基准解析。

[document]
reference_doc = "reference.docx"
toc = true
number_sections = true
lang = "zh-CN"

[pandoc]
from_format = "markdown+yaml_metadata_block+tex_math_dollars+fenced_divs+bracketed_spans"
standalone = true
resource_paths = [".", "assets"]
extra_args = []

命令行参数的优先级高于配置文件。未知配置项会直接报错，不会被静默忽略。

默认排版

• 中文正文：宋体，10.5 pt。
• 中文标题：黑体，加粗；一级至四级标题分别为 16、14、12、11 pt。
• 标题和正文默认使用黑色字体。
• 默认关闭代码语法高亮，因此不会自动出现蓝色或其他彩色代码字体。
• 如需启用 Pandoc 代码高亮，可在配置中填写 highlight_style。

支持的 Markdown

HanDocx 由 Pandoc 负责解析 Markdown，因此支持标题、列表、表格、链接、脚注、 本地及远程图片、代码块、YAML 元数据、引用和 LaTeX 数学公式。

行内公式：$E = mc^2$

$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$

使用 fenced div 插入显式分页：

::: pagebreak
:::

自定义 Word 模板

运行 handocx init 后，用 Word 或 WPS 打开 reference.docx，修改命名样式， 不要逐段直接格式化。最重要的样式包括 Normal、Title、Subtitle、 Heading 1 至 Heading 3、Caption、Block Text 和 Source Code。

详细步骤参见自定义 Word 模板。

开发

python -m pip install -e ".[dev]"
python -m unittest discover -s tests -v
python scripts/build_reference.py
python scripts/create_demo_asset.py
handocx doctor

单元测试不会下载程序或访问网络。GitHub Actions 会在 Windows、Linux 以及 Python 3.11、3.12 上执行真实 Pandoc 转换。

设计原则

• 不重复实现 Markdown 解析器或 OOXML 生成器。
• 子进程参数始终使用列表传递，不使用 shell=True。
• 默认模板由 scripts/build_reference.py 可复现地生成。
• Pandoc 转换失败时保留原始标准错误输出。
• 输出文件不得覆盖输入的 Markdown 文件。

扩展机制参见项目架构，发布流程参见发布指南。

后续计划

• 商务报告、学术论文和公文模板包。
• 无需在线服务的 Mermaid 本地渲染。
• DOCX 结构检查和 PDF 截图回归测试。
• 本地网页界面和 REST API。
• GB/T 7714 及常见期刊引用样式。

许可证

HanDocx 使用 MIT 许可证。Pandoc 是独立的 GPL 项目；HanDocx 仅调用 Pandoc 可执行文件，不随本项目重新分发 Pandoc。