Any document → clean, LLM-ready Markdown. On your own server, on every device you own.

Read this in: English (this file) · русский

TrimItDown turns PDF, Word (docx), PowerPoint (pptx), Excel (xlsx/xls) and Outlook (.msg) files into clean, readable Markdown — ready to paste into Claude/ChatGPT, Obsidian, Notion, or any markdown vault. It runs as an iPhone/iPad app (installed straight from Safari, no App Store), a single-file Windows program, a macOS app, and a self-hosted Docker server — with one shared archive of conversions across all your devices.

The PDF engine

Most converters — including the stock MarkItDown PDF path — stumble on real-world PDFs in three measurable ways: they glue words together, invent tables out of ordinary prose, and drop genuine ruled tables. Measured over 891 real documents from two independent collections, the stock converter emitted 5,624 table rows on documents containing no ruled grid at all — prose reshaped into tables — against 2 from the engine below. On the 885 of those documents that are not broken at the source, it roughly halves glued words (107 runs vs 53). Those corpora are third-party copyrighted material and are not redistributable — the full method, the numbers, the cases where this engine loses, and what a reader can reproduce are in docs/pdf-engine.md.

So TrimItDown replaced it with a custom extraction engine:

• Words split at a measured word-gap threshold — a fraction of the font size, not a fixed point value, so it holds across small print and large headings alike.
• A dedicated table-detection stage validates every candidate grid by how its cells are actually filled (a row-fill vote), instead of trusting every ruled rectangle. Diagrams and decorative frames get rejected; their text flows back into prose instead of vanishing.
• Genuine ruled tables render as honest Markdown tables, cell for cell.

Here is one document converted both ways. The file is committed to this repo, so you can run the comparison yourself:

python scripts/compare_pdf_engines.py tests/data/sample-service-report.pdf

Stock converter — a phantom empty column splits the data, shifting every value one column right of its header:

| Parameter                 | Unit | Before service |     | After service | Limit |
| ------------------------- | ---- | -------------- | --- | ------------- | ----- |
| Supply airflow            | m³/h |                | 352 | 398           | ≥ 380 |
| Extract airflow           | m³/h |                | 341 | 402           | ≥ 380 |
| Filter pressure drop      | Pa   |                | 184 | 92            | ≤ 150 |
| Heat recovery efficiency  | %    |                | 61  | 78            | ≥ 70  |
| Motor current, supply fan | A    |                | 1.9 | 1.6           | ≤ 2.2 |

TrimItDown — the table as it appears on the page:

| Parameter | Unit | Before service | After service | Limit |
| --- | --- | --- | --- | --- |
| Supply airflow | m³/h | 352 | 398 | ≥ 380 |
| Extract airflow | m³/h | 341 | 402 | ≥ 380 |
| Filter pressure drop | Pa | 184 | 92 | ≤ 150 |
| Heat recovery efficiency | % | 61 | 78 | ≥ 70 |
| Motor current, supply fan | A | 1.9 | 1.6 | ≤ 2.2 |

One sample proves nothing about a corpus, and ours is third-party material we cannot publish. So the measurement ships instead of the documents — point it at your own PDFs and it runs both converters over all of them and prints a comparable summary, counts only, no filenames:

python scripts/measure_corpus.py /path/to/your/pdfs --limit 50

Please send that summary back whatever it says — a win, a loss, or a tie (issue template). Results collected only when something breaks are a sample made of breakage, and nothing honest can be concluded from it. Pooled across enough corpora, these numbers stop being one person's collection. Details in docs/pdf-engine.md.

In short: we add the table-validation stage that the classic tabula-java pipeline has and Python extractors lack, expressed as a cell-fill vote on pdfplumber's ruled grids, with per-grid fallback to prose — no ML models, no cloud, small enough to ship inside a portable binary. Every non-PDF format still goes through MarkItDown.

Why TrimItDown

• Made for the LLM workflow. Clean Markdown out, a live preview, and a token counter that shows what a document will cost before you paste it into a model's context.
• Your files never leave your infrastructure. Conversion happens on your own server (home NAS, VPS) or fully offline on your computer. No third-party SaaS, no per-page fees.
• One archive, every device. Convert on your phone — the result is already on your computer, and vice versa. Searchable, with batch conversion and ZIP export.
• A real app experience everywhere. iPhone PWA installed from Safari (no App Store), a single-file Windows exe, a macOS app. Russian and English UI, light/dark, two color themes.

Get it

Platform	How
Terminal (any OS)	uv tool install trimitdown — no GUI, no system prompts, see Command-line package
Windows	x64 only: scoop bucket add trimitdown https://github.com/serjdrej/trimitdown then scoop install trimitdown — Start-menu entry, scoop update trimitdown later. Or download TrimItDown-windows-x64.exe from Releases — a single file, no installer
macOS 11+	From Releases: Apple Silicon (M1 and later) → TrimItDown-macOS-arm64.dmg; Intel Mac → TrimItDown-macOS-x86_64.dmg. Mount it, drag TrimItDown into Applications, then First launch
iPhone / iPad	Served by your own Docker server — open it in Safari → Share → Add to Home Screen
Docker server	See Self-hosting below

The desktop apps work fully offline out of the box. Point them at your server in Settings to get the shared archive.

First launch

The apps are not signed with a developer certificate, so each platform asks once before it will run a program it does not recognise. This happens once per downloaded copy, not on every launch.

• macOS — the first launch is refused; dismiss the warning, allow the app under System Settings → Privacy & Security → Open Anyway, then launch it again.
• Windows — SmartScreen → More info → Run anyway. Installing through scoop does not raise this prompt at all: scoop does not tag what it downloads as coming from the web, so there is nothing for SmartScreen to warn about.

Binaries are not signed. The release workflow creates SHA256SUMS for every desktop artifact: a hash verifies the downloaded file's integrity, but does not authenticate its publisher. If a release includes SHA256SUMS, compare the hash for your downloaded filename with its matching row:

Get-FileHash .\TrimItDown-windows-x64.exe -Algorithm SHA256

shasum -a 256 TrimItDown-macOS-arm64.dmg

Command-line package

Requires Python 3.10+. To install it for good: uv tool install trimitdown, or pipx install trimitdown. A plain pip install into the system Python is refused on many distributions and on Homebrew (PEP 668), which is why both commands above put the package in an isolated environment. The package is trimitdown; trimitdown-pdf is its dependency and is not needed as a separate end-user install.

trimitdown convert report.pdf -o report.md

Without -o, Markdown goes to standard output; input can arrive as a stream: trimitdown convert - --type pdf. The CLI works fully offline.

To try it once without installing: uvx trimitdown convert report.pdf. It does not create a persistent trimitdown command, but downloaded packages and environments may remain in uv's cache.

Update an installed CLI with uv tool upgrade trimitdown or pipx upgrade trimitdown; remove it with uv tool uninstall trimitdown or pipx uninstall trimitdown.

Self-hosting

The Docker server is the source of truth: it converts, stores the shared archive, and serves the iPhone PWA. This repository does not publish a ready-made Docker image; these commands build a chosen release from source. You need Git, Docker with Compose, and OpenSSL. Select a release tag from the Releases page before building rather than building main. Clone into a separate directory, not inside an existing clone, to avoid nesting trimitdown/docker-server/trimitdown/docker-server.

git clone https://github.com/serjdrej/trimitdown.git && cd trimitdown && git checkout <release-tag> && cd docker-server
./setup.sh YOUR_SERVER_ADDRESS
docker compose up -d --build      # Compose v1: docker-compose up -d --build

setup.sh prints the first-visit link; the secret moves into a cookie, and later visits need only https://YOUR_SERVER:8002.

One shared secret, not accounts — the server holds one archive and belongs to one person. It refuses to start serving without one. docker compose publishes the port on every interface, and Docker's own firewall rules mean a ufw deny on the host does not close it; bind to 127.0.0.1 in docker-compose.yaml if you want this machine only.

Full instructions — certificate generation, trusting it on iOS/Windows/macOS, and the API — in docker-server/README.en.md.

Uninstall

Removing the program or container does not remove your documents automatically.

Channel	Remove the program	What remains
uv tool	uv tool uninstall trimitdown	Markdown files you created and uv's package cache
pipx	pipx uninstall trimitdown	Markdown files you created and pip/pipx caches
Scoop	scoop uninstall trimitdown; optionally scoop bucket rm trimitdown	%APPDATA%\TrimItDown
Windows EXE	Delete the downloaded EXE	%APPDATA%\TrimItDown
macOS DMG	Delete TrimItDown.app from Applications	~/Library/Application Support/TrimItDown
Docker	From docker-server/: docker compose down	The trimitdown-web:latest image, clone, .env, certs/, and archive/
iPhone/iPad PWA	Remove it from the Home Screen	Safari website data, the cookie, and any installed certificate

Back up needed conversions before deleting archive; removing the app or container alone does not clear it. Certificate trust is system state: removing an app or PWA does not remove it. Remove the profile on iOS, the certificate from CurrentUser\Root on Windows, or the certificate from Keychain on macOS when you no longer trust this server.

Screenshots

Archive, shared across devices	Settings

Ocean theme, light	Ocean theme, dark

The iPhone PWA — home screen	Converting a PDF

How it works

• The Docker server is a FastAPI service with HTTPS; the archive lives on the server. The same service serves the PWA for iPhone.
• The Windows/macOS apps check at startup whether your server is reachable: if yes, they open straight on it (shared archive); if not, they spin up a bundled local server and work fully offline. The shell is pywebview (WebView2 / WKWebView), packaged with PyInstaller.
• Conversion: PDFs go through TrimItDown's own engine (trimitdown-pdf, built on pdfplumber); every other format goes through Microsoft's MarkItDown.

Repository layout

• src/trimitdown/ — published CLI package and conversion logic
• core/ — HTTP-layer and archive support for the desktop and server applications
• packages/trimitdown-pdf/ — separately published PDF engine
• docker-server/ — the self-hosted service + iPhone PWA
• static/, main.py, server_app.py — desktop apps (UI, entry point, offline mode)
• tests/ — unit tests + a labeled corpus harness for the table-detection stage
• docs/pdf-engine.md — PDF engine design, measurements, reproduction

Contributing

Bug reports and PRs are welcome — see CONTRIBUTING.md. DEVELOPMENT.md documents the dev setup and the desktop build internals.

Limitations

• Best fit: text-based PDFs and ruled tables. Borderless and whitespace-aligned tables are outside the PDF engine's scope.
• TrimItDown does not perform OCR. Scanned or image-only pages are marked as having no extractable text layer.
• Full multi-column layout reconstruction is out of scope, including reading order across columns, headers/footers, and figure captions.
• The server's self-signed HTTPS certificate needs a one-time manual trust on each device (iOS: profile + full trust; Windows: import into CurrentUser\Root; macOS: Keychain).
• Unsigned binaries: one manual approval per downloaded copy — see First launch.

License and credits

Code is MIT. Non-PDF conversion is powered by MarkItDown (Microsoft, MIT); the bundled third-party licenses are listed in THIRD_PARTY_NOTICES.md.