Milldown User Guide

Everything Milldown does, and how to use it. If you just want to get going, read Your first conversion and skim the rest when you need it.

Installing

Milldown needs an Apple Silicon Mac (M1 or later) running macOS 14 Sonoma or newer. Intel Macs are not supported.

1. Open the downloaded .dmg.
2. Drag Milldown into your Applications folder.
3. Launch it from Applications.

There is nothing else to install. The conversion engine ships inside the app, which is why the download is around 175 MB — Milldown never uses, requires, or modifies any Python on your system.

Your first conversion

1. Drag a PDF or Word document onto the Milldown window.
2. It converts automatically. The Markdown appears on the right.
3. Press ⇧⌘C to copy it, or ⌘S to save it as a .md file.

That's the whole core loop. Everything else in this guide is refinement on top of it.

The interface

Milldown is a three-part window:

• The file list on the left — everything you've added, with its status and how many tokens it saved. Names are truncated in the middle; hover to see the full path.
• The output on the right — the converted Markdown, either rendered or as raw text you can edit.
• The Options inspector on the far right — toggle it with the Options toolbar button. Per-conversion settings live here.

Before you add anything, the window shows a single drop target. The split view appears with your first file.

Every toolbar button has a tooltip explaining what it does and its keyboard shortcut — hover for a moment if you're unsure.

Five ways to add files

Files convert as soon as they're added. Add as many as you like — they queue, and the toolbar shows progress as done / total. Stop cancels the whole batch immediately; anything not yet converted returns to the queue rather than being marked failed.

Supported formats

What's refused, and why

Milldown refuses some files on purpose, with an explanation, rather than producing something that looks converted but isn't.

Folders and whole trees

Drop a folder and Milldown converts everything convertible inside it, at any depth, and writes a Markdown mirror that preserves your subfolder structure. Unsupported files are skipped with a reason rather than failing the batch.

Mirrors are written into a Markdown subfolder inside the folder you dropped, never scattered alongside your originals.

Web pages and YouTube

Press ⌘L and paste any URL.

• Articles and blog posts — navigation, scripts and styling are stripped; headings, tables and links survive.
• Wikipedia — recognised specially and formatted properly.
• YouTube — you get the video's title, description, keywords, runtime and full transcript as one Markdown document.

YouTube needs the video to have captions, either the creator's or YouTube's automatic ones. Most videos do. Auto-captions carry auto-caption quality — proper nouns and technical terms sometimes come out creative. Private, age-restricted and region-blocked videos aren't accessible, and Milldown says so rather than handing you an empty document.

Preview and Markdown views

Two tabs above the output:

• Preview renders the Markdown as formatted text — useful for checking the conversion looks right.
• Markdown shows the raw source, and it's editable. Trim boilerplate, delete a section you don't need, fix a heading. The token count updates live as you type.

Editing changes what gets copied, saved, chunked and packed. It does not touch your original file.

Clean Up

Refine ▸ Clean Up strips conversion noise without touching your content:

• Repeated running headers and footers — short lines appearing four or more times, the signature of per-page boilerplate.
• Standalone page-number lines.
• Trailing whitespace and invisible characters (zero-width spaces, non-breaking spaces).
• Runs of blank lines, collapsed to one.

It never touches anything inside a fenced code block. When it finishes it tells you exactly what it removed — or says "Already clean" if there was nothing to do. Refine ▸ Revert Cleanup restores the text exactly as it was.

RAG chunk export

For retrieval pipelines, Refine offers two exports:

• Export RAG Chunks… — numbered Markdown files (report-001.md, report-002.md…) in a folder you choose.
• Export Chunks as JSONL… — a single .jsonl file, one JSON object per line, ready to stream into a vector store.

Chunks split on heading boundaries rather than mid-sentence, so each one stays semantically whole. Target size is set in Options ▸ Chunk Export: roughly 512, 1,024 or 2,048 tokens. Smaller chunks retrieve more precisely; larger ones keep more context together.

Combine with provenance front matter so every chunk carries its source path, timestamp and hash.

Context Packs

⇧⌘K, or Context Pack in the toolbar, merges every converted document into one Markdown file with a table of contents and clear per-document separators.

This is for the case where you want an AI to consider a whole set of documents at once — a project's specs, a quarter's reports, a folder of research — as a single paste rather than a dozen uploads. The pack appears in the file list like any other document, so you can edit, clean and save it.

YAML front matter

Options ▸ Output ▸ Front matter prepends a YAML header to every conversion. Three choices:

• None — just the Markdown.
• Provenance — title, source, converted timestamp, sha256 of the original, and generator. For archives, audits and RAG, where you need to prove where a document came from.
• Publishing — a Hugo/Jekyll-style header ready to drop into a static site.

---
title: "quarterly-report.pdf"
source: "/Users/you/Documents/quarterly-report.pdf"
converted: 2026-08-06T14:22:31Z
sha256: 9f2b1c...
generator: Milldown
---

The SHA-256 is of the original file, so years later you can prove the Markdown came from that exact document.

Spreadsheets as CSV

By default an .xlsx becomes Markdown tables. Turn on Spreadsheets as CSV in Options and you get plain CSV instead — about 39% fewer tokens for the same data, because Markdown tables spend a lot of characters on pipes and alignment rows.

Use Markdown tables when a human will read it; use CSV when a model or a script will. Multi-sheet workbooks get a # Sheet: Name header before each sheet.

The setting applies to the next conversion — use Convert All (⌘R) to re-run existing files with it.

OCR for scanned PDFs

When a PDF has little or no embedded text — a scan, a photographed contract, an old fax — Milldown recognises it with Apple's Vision framework, entirely on your Mac. Nothing is uploaded.

It happens automatically; a purple On-device OCR badge appears above the output so you always know the text was recognised rather than extracted. You can turn it off in Options ▸ Output.

OCR is slower than text extraction and its accuracy depends on scan quality. Skewed or low-resolution pages produce more errors — worth a read-through before feeding the result to anything important.

Getting output out

If two documents would save under the same name, Milldown adds a numeric suffix rather than overwriting — and the comparison is case-insensitive, matching how your disk actually behaves.

How token savings are calculated

Locally, with the o200k tokenizer (the one used by current GPT and Claude-class models), comparing Milldown's output against the realistic alternative for that file type:

The counter in the toolbar totals the session. Click it to open pricing options.

Why some files show no savings

Word documents, PowerPoint decks and YouTube videos deliberately show a token count with no savings figure. This is not an oversight.

It would be easy to claim ~97% for a .docx by comparing Markdown against the raw OOXML inside the file. But nothing sends a model raw OOXML — every tool, and every chat client you drop a document into, extracts the text first. Measured against that, Markdown costs the same: 1,042 tokens versus 1,045 on a real document.

A video is starker still: there is no way to give one to an LLM except as a transcript, so the transcript is the baseline, not a saving against one.

What conversion buys you in those cases is structure — real headings, tables and lists that plain extraction flattens — plus a file you can diff, index and archive. That's worth having. It just isn't a token saving, so Milldown doesn't call it one.

Choosing a pricing rate

Options ▸ Token Savings, or click the counter in the toolbar. Presets cover Claude Opus 5 / Sonnet 5 / Haiku 4.5, GPT-5 and GPT-5 mini class, Gemini Pro and Flash class, and open-weight/self-hosted. Custom rate… lets you enter your own.

Projected uses (1× / 10× / 100×) reflects that a document is re-billed on every conversation turn and every RAG query. The projections assume uncached pricing; with prompt caching enabled, repeat-use savings are roughly 3–5× smaller, though still real.

Watch folders

Nominate a folder in Settings ▸ Watch Folders and anything added to it is converted automatically into a Markdown subfolder. Subfolders are watched too, including ones created later.

Useful for a scanner's output folder, a shared drive of incoming reports, or a Downloads subfolder you drop research into.

Milldown waits for a file to stop changing before converting, so a large file still being written or synced isn't converted half-finished. Because mirrors live in a dedicated subfolder, converted output is never itself re-converted.

The command line

Two options, in the Milldown menu:

• Install Command-Line Tool… installs milldown into /usr/local/bin. Needs your admin password once. Available everywhere afterwards — scripts, Makefiles, CI.
• Open Terminal with milldown (⇧⌘T) opens a terminal with milldown already on its PATH, installing nothing.

milldown report.pdf -o report.md
milldown https://example.com/article
cat page.html | milldown -x .html
milldown --help

The tool has full option parity with the engine. It points at the engine inside your copy of Milldown.app, so reinstall it from the menu if you move the app.

URL scheme and Shortcuts

Milldown registers a milldown:// scheme that works from Shortcuts' Open URLs action, scripts, and launchers:

milldown://convert?path=/absolute/path/to/file.pdf
milldown://convert?path=/absolute/path/to/file.pdf&copy=1

With copy=1 the Markdown lands on your clipboard as soon as it's ready.

Menu bar

The M icon in your menu bar is a permanent drop target. Drop a file on it and the Markdown goes straight to your clipboard, ready to paste — no need to bring the main window forward. The panel also converts the clipboard, shows the session's token savings, and reopens the main window.

Finder integration

• Right-click → Convert to Markdown on any file (it may appear under the Services submenu the first time).
• Open With → Milldown for supported types.
• Drop files on the Dock icon.

All three work whether Milldown is running or not.

Settings reference

⌘, opens Settings. Options that apply to a single conversion also live in the inspector, so you can change them in context.

Session restore (on by default) brings back your file list and converted Markdown exactly as you left it — no re-converting, no re-running OCR. Turning it off also deletes the saved session from disk. Session data lives in ~/Library/Application Support/Milldown.

Keep data URIs retains base64-encoded images inline instead of truncating them. They are enormous in token terms — leave this off unless you specifically need the image data.

Keyboard shortcuts

Azure options

Azure Document Intelligence and Azure Content Understanding route documents to Microsoft's cloud services instead of converting them offline. They exist because some organisations already pay for them and get better results on difficult layouts. If you don't know you need them, you don't.

Using them requires your own Azure endpoint and credentials. Milldown doesn't provide or proxy either.

Privacy and network activity

Your documents are converted entirely on your Mac, including OCR, and are never uploaded. There is no account and no telemetry. Local conversion works with Wi-Fi off — try it.

Milldown makes exactly four kinds of network request, none of which carry a file from your disk:

1. Fetching a web page or YouTube transcript you explicitly paste.
2. Checking milldown.app for application updates.
3. Verifying your licence key when you activate, and periodically thereafter.
4. Only if you switch them on: the Azure services above — which do send your documents.

Licensing

Milldown is free for 14 days with every feature unlocked and no account required. After that a $39 one-time licence covers up to 3 Macs, for personal and commercial use. A $149 Team licence covers 10 seats. Prices exclude VAT/sales tax, added at checkout where applicable; Stripe acts as merchant of record and issues your receipt.

Your purchase includes 12 months of updates. When that period ends Milldown keeps working exactly as it is, forever — you simply stop receiving new versions unless you renew for $19/year. Nothing is billed automatically and no feature is ever switched off.

Enter your key in Settings ▸ General ▸ Manage License. To move a Mac off your licence, use Deactivate there first — it frees the seat immediately.

When the trial ends, conversion stops and nothing else changes. Documents already converted stay in the app, and everything you saved is plain Markdown you own outright.

Your licence key arrives by email the moment payment completes. It is stored in your macOS Keychain. The trial date is a plain file in Application Support — deliberately not the Keychain, because a timestamp is not a secret and asking for your login password to read one would be absurd.

Updates

Milldown ▸ Check for Updates…. Updates are cryptographically signed and verified before installation. If the update server can't be reached, Milldown tells you which problem it hit — no network, server down — rather than showing a raw error.

Your licence includes twelve months of updates from the date of purchase. Settings ▸ General shows the exact date under Updates.

When that period ends, nothing is switched off. Every feature keeps working, your licence stays valid, and the version you have runs indefinitely. The only change is that versions published after your window closed are no longer offered — Milldown says so plainly if you check for updates, rather than pretending you are up to date.

Entitlement is judged on when a version was published, not on when you install it. A version released inside your window is yours to install at any point in the future, including years later.

Troubleshooting

A file converted but the output looks wrong

Check the Markdown tab rather than Preview — occasionally the source is fine and only the rendering looks odd. If the source really is wrong, the original may use an unusual layout the engine reads differently; try Clean Up, or edit directly.

"This file is damaged or incomplete"

The Office or EPUB file's internal structure couldn't be read — usually a truncated download or an interrupted sync. Fetch a fresh copy, or open it in its original app and re-save.

A scanned PDF produced nothing

Confirm OCR is on in Options ▸ Output. Very low-resolution or heavily skewed scans may yield little; straightening and rescanning at 300 dpi helps a lot.

YouTube says no transcript is available

The video has no captions, or YouTube is declining to serve them — common for age-restricted and very new uploads. Milldown can't generate captions itself, because that would mean uploading the audio.

A conversion is stuck

Click Stop. Any single conversion is also capped at ten minutes, after which it fails rather than hanging forever. Very large PDFs with OCR are legitimately slow — a few hundred pages can take several minutes.

The milldown command stopped working

The installed tool points at the engine inside your copy of Milldown.app. If you moved or replaced the app, reinstall it from Milldown ▸ Install Command-Line Tool….

Something else

Email support@milldown.app. Including the file type, what you expected, and what you got makes it far quicker to fix.