快速开始
GordonKit 文档转换器
将 DOCX 与其他文档格式转换为 PDF、HTML、Markdown、图片等格式，并可通过 Python 库、CLI 或 HTTP API 使用。
关于此项目
此 GordonKit 开源项目负责协调 Microsoft Word、LibreOffice、Gotenberg 或 Pandoc 进行文档排版，并让引擎选择、验证、fallback 报告与转换结果保持明确且可诊断。
使用接口
依工作流程选择适合的接口。所有接口都通过同一个 application service，并保留结构化结果、引擎策略与诊断信息。
Python 库
使用具类型的公开契约，执行单文件转换、隔离式批处理、引擎探测与 service injection。
from gordon_doc_converter import convertCLI
执行转换、比较与引擎检查，并输出稳定 JSON 结果供 script 与 CI 流程使用。
gordon-doc convert report.docx --to pdfHTTP API
安装 FastAPI extra，创建具认证 hooks、流量限制与有限并发能力的私有部署。
POST /conversions格式支持：本机安装
一个部署能转换什么，取决于它具备哪些引擎，而不是通过哪种接口调用。此表假设 PATH 上具备 LibreOffice、Pandoc 与 wkhtmltopdf，逐页图片已安装 images extra；Word COM 策略则需要安装 Word 的交互式 Windows 桌面环境。
| 输入 | DOCX | ODT | HTML | Markdown | YAML | JSON | 页图 | |
|---|---|---|---|---|---|---|---|---|
| DOCX | 不适用 | Auto | LO | ✓ | ✓ | ✓ | ✓ | |
| R | 不适用 | R | ✓ | ✓ | ✓ | ✓ | ✓ | |
| ODT | LO | LO | 不适用 | ✓ | ✓ | ✓ | ✓ | |
| HTML | P | W | LO | 不适用 | ✓ | ✓ | ✓ | |
| Markdown | P | W | LO | ✓ | 不适用 | ✓ | ✓ |
格式支持：容器镜像
官方镜像安装的是 libreoffice-writer 与 api、gotenberg 两个 extra，因此所有优先使用 wkhtmltopdf 或 Pandoc 的路径都改由 LibreOffice 排版，并报告指出替代引擎的 ENGINE_FALLBACK warning。镜像提供的 HTTP API 只负责 DOCX 转 PDF；表中其余路径通过 cli Compose profile 执行。
| 输入 | DOCX | ODT | HTML | Markdown | YAML | JSON | 页图 | |
|---|---|---|---|---|---|---|---|---|
| DOCX | 不适用 | Auto | LO | ✓ | ✓ | ✓ | ✓ | — |
| R! | 不适用 | R | ✓ | ✓ | ✓ | ✓ | — | |
| ODT | LO | LO | 不适用 | ✓ | ✓ | ✓ | ✓ | — |
| HTML | LO! | LO! | LO | 不适用 | ✓ | ✓ | ✓ | — |
| Markdown | LO! | LO! | LO | ✓ | 不适用 | ✓ | ✓ | — |
安装
先安装核心包，再依部署需求加入可选能力。
uv add gordon-doc-converter
uv add 'gordon-doc-converter[images,gotenberg]'第一次转换
从来源路径创建请求。服务会选择策略允许的引擎、验证暂存输出，并只在验证成功后发布。
from pathlib import Path
from gordon_doc_converter import ConversionRequest, convert
request = ConversionRequest.from_source(Path("report.docx"))
result = convert(request)
print(result.artifacts[0].path)