Getting Started
GordonKit Document Converter
Convert DOCX and other document formats to PDF, HTML, Markdown, images, and more through a Python library, CLI, or HTTP API.
About this project
This open-source GordonKit project orchestrates Microsoft Word, LibreOffice, Gotenberg, or Pandoc for document rendering. It keeps engine selection, validation, fallback reporting, and conversion results explicit and diagnosable.
Ways to use it
Choose the interface that fits your workflow. Every interface enters through the same application service and preserves structured results, engine policy, and diagnostics.
Python Library
Use typed public contracts for single conversions, isolated batches, engine probes, and service injection.
from gordon_doc_converter import convertCLI
Convert, compare, inspect engines, and emit stable JSON results for scripts and CI workflows.
gordon-doc convert report.docx --to pdfHTTP API
Install the FastAPI extra for private deployments with authentication hooks, rate limits, and bounded concurrency.
POST /conversionsFormat support: local install
What a deployment can convert depends on the engines it carries, not on the interface it is driven through. This matrix assumes LibreOffice, Pandoc, and wkhtmltopdf on PATH, the images extra installed for page images, and, for the Word COM policy, an interactive Windows desktop with Word.
| Input | DOCX | ODT | HTML | Markdown | YAML | JSON | Images | |
|---|---|---|---|---|---|---|---|---|
| DOCX | Not applicable | Auto | LO | ✓ | ✓ | ✓ | ✓ | |
| R | Not applicable | R | ✓ | ✓ | ✓ | ✓ | ✓ | |
| ODT | LO | LO | Not applicable | ✓ | ✓ | ✓ | ✓ | |
| HTML | P | W | LO | Not applicable | ✓ | ✓ | ✓ | |
| Markdown | P | W | LO | ✓ | Not applicable | ✓ | ✓ |
Format support: container image
The published image installs libreoffice-writer with the api and gotenberg extras, so every route that prefers wkhtmltopdf or Pandoc is served by LibreOffice instead and reports an ENGINE_FALLBACK warning naming the substituted engine. The HTTP API the image serves converts DOCX to PDF only; the rest of this matrix is reached through the cli Compose profile.
| Input | DOCX | ODT | HTML | Markdown | YAML | JSON | Images | |
|---|---|---|---|---|---|---|---|---|
| DOCX | Not applicable | Auto | LO | ✓ | ✓ | ✓ | ✓ | — |
| R! | Not applicable | R | ✓ | ✓ | ✓ | ✓ | — | |
| ODT | LO | LO | Not applicable | ✓ | ✓ | ✓ | ✓ | — |
| HTML | LO! | LO! | LO | Not applicable | ✓ | ✓ | ✓ | — |
| Markdown | LO! | LO! | LO | ✓ | Not applicable | ✓ | ✓ | — |
Install
Install the core package, then add only the optional capabilities required by your deployment.
uv add gordon-doc-converter
uv add 'gordon-doc-converter[images,gotenberg]'First conversion
Create a request from a source path. The service selects an allowed engine, validates staged output, and publishes only after validation succeeds.
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)