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 convert

CLI

Convert, compare, inspect engines, and emit stable JSON results for scripts and CI workflows.

gordon-doc convert report.docx --to pdf

HTTP API

Install the FastAPI extra for private deployments with authentication hooks, rate limits, and bounded concurrency.

POST /conversions

Format support

Use this matrix to see the project's primary conversion capabilities. Some routes require an optional engine or output package as noted.

Supported input and output formats
Input	DOCX	PDF	ODT	HTML	Markdown	YAML	JSON	Images
DOCX	Not applicable	Auto	LO	✓	✓	✓	✓	PDF
PDF	—	Not applicable	—	✓	✓	✓	✓	✓
ODT	LO	LO	Not applicable	✓	✓	✓	✓	PDF
HTML	P	W	LO	Not applicable	✓	✓	✓	PDF
Markdown	P	W	LO	✓	Not applicable	✓	✓	PDF

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)