Explicit page routing instead of silent garbled text
Every PDF page is extracted by pdf-inspector and verified against an independent pypdf decode, comparing character integrity across scripts (Cyrillic, Latin, Greek, CJK, and others).
1. Primary Extract
pdf-inspector reads layout structure, headings, and Markdown tables from each page.
2. Independent Cross-Check
pypdf decodes the same page independently to catch broken ToUnicode maps and Cyrillic-to-Latin substitution.
3. Deterministic Route
Each page receives one of five explicit outcomes:
Built for reliable LLM ingestion
Minimum tokens, honest failure modes, and zero external dependencies at runtime.
Tracked Changes & Hidden Element Guard
Before converting .docx, .doc, or .rtf, trimitdown checks for unaccepted revisions and rejects ambiguous files by default (accept via --accept-changes for DOCX). Omitted headers, comments, or images are flagged in a top HTML comment and stderr while preserving footnotes.
Structured Scan Review Bundles
Pass --review-dir out/ to generate document.md, manifest.json, REVIEW.md, PNG renders in pages/, and optional Tesseract text candidates in candidates/. Stitch verified text back in with trimitdown assemble.
CLI & Clean Python Library
Pipe stdin/stdout in shell workflows (trimitdown convert - --type pdf), export JSON diagnostics with --report PATH, or call convert_path() directly in Python to inspect result.text, result.pages, and result.tokens_after.
100% Local & Offline
Documents stay on your machine. Core PDF, TXT, and Markdown support installs cleanly without heavy ML weights; add the [office] extra only when you need Office, EPUB, CSV, or HTML conversion.
Install & run in seconds
Requires Python 3.10+. Works with uv, pipx, or standard virtual environments.
# Core package (PDF, .txt, .md)
uv tool install trimitdown # or: pipx install trimitdown
# With Office, EPUB, CSV, and HTML support (firecrawl-anydoc + markdownify)
uv tool install "trimitdown[office]" # or: pip install "trimitdown[office]"
# One-off run without permanent installation
uvx trimitdown convert report.pdf
# Basic conversion (omit -o to write to stdout)
trimitdown convert report.pdf -o report.md
# Insert <!-- page N --> anchors and save a JSON routing report
trimitdown convert report.pdf --page-anchors --report report.json -o report.md
# Convert from stdin or accept DOCX tracked changes
trimitdown convert - --type pdf < report.pdf
trimitdown convert contract.docx --accept-changes -o contract.md
# Render specific pages or run the scan review workflow
trimitdown render report.pdf --pages 5,7 -o img/
trimitdown convert scan.pdf --review-dir out/
trimitdown assemble out/ -o report.md
from trimitdown.convert import convert_path
from trimitdown.review import prepare_review, assemble, render_pages
result = convert_path("report.pdf")
print(result.tokens_after) # cl100k token count of resulting Markdown
print(result.pages) # per-page routing decisions and reasons
print(result.text) # Markdown output
# Accept tracked changes in Word documents
docx_result = convert_path("contract.docx", accept_changes=True)
Supported file formats
Unsupported container or binary types are rejected explicitly instead of producing silent garbage.
| Package / Extra | Formats | Backend & Behavior |
|---|---|---|
trimitdown (core) |
.pdf, .txt, .md |
pdf-inspector + pypdf dual-decoder check for PDF; UTF-8 pass-through for plain text and Markdown. |
trimitdown[office] |
.docx, .doc, .rtf, .xlsx, .xls, .ods, .csv, .pptx, .ppt, .odp, .epub |
Converted via firecrawl-anydoc with tracked-changes inspection on Word/RTF (.odt currently rejected). |
trimitdown[office] |
.html, .htm |
Converted via markdownify with scripts and styles stripped. |
| Explicitly rejected | Encrypted PDF, .msg, .json, .xml, .zip, images, audio |
Fails fast with a clear error message rather than returning partial or binary noise. |
Design notes and known limitations
What trimitdown intentionally does — and does not — attempt to do.
Why is OCR not bundled directly inside trimitdown?
Keeping OCR external avoids shipping large model weights in a lightweight CLI. If tesseract is installed locally, --review-dir automatically runs it to populate candidates/pNNNN.txt alongside rendered page images for human or vision-model review.
How does the dual-decoder check affect speed and Latin-only PDFs?
Cross-checking with pypdf is slower than running pdf-inspector alone, which is an intentional trade-off for accuracy. Pure Latin character loss is not gated by default (GATE_LATIN is off), while Cyrillic-to-Latin corruption is caught automatically. Text embedded underneath an image is treated as a text layer.
Where did the Docker server and desktop apps go?
Starting in v0.2.0, the standalone Python CLI and library became the primary product. The earlier self-hosted Docker server, iOS PWA, and Windows/macOS wrappers remain preserved in repository history up to release v0.1.2.