Milldown User Guide

macOSWindows

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

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 ⇧⌘CCtrl+Shift+C to copy it, or ⌘SCtrl+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 ⌘LCtrl+L and paste any URL.

• Articles and blog posts — scripts and styling are stripped and the structure survives: headings, tables, links and emphasis. The rest of the page body comes with it, so a site’s navigation and footer usually appear at the top and bottom, ready to trim.
• 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 in a folder you choose. The name is built from the source file, extension included: report.pdf becomes report-pdf-001.md, report-pdf-002.md and so on.
• 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 and every chunk's own YAML header absorbs the source path, timestamp and hash — the document's front-matter block itself is never duplicated into the chunk text.

Context Packs

⇧⌘KCtrl+Shift+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 (local files only — a converted URL has no file to hash), 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 — 12–29% 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 (⌘RCtrl+R) to re-run existing files with it.

OCR for scans and images

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.with the Windows OCR engine, entirely on your PC. Nothing is uploaded. The same applies to JPEG and PNG images: if the file carries no text metadata, the pixels are OCR'd on-device, and an image with no readable text at all is refused with an explanation rather than marked converted with empty output.

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 with OCR scans & images 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 OpenAI's o200k tokenizer as a consistent estimate — it is not Anthropic's, and absolute counts vary by provider — comparing Milldown's output against the realistic alternative for that file type. The figures are estimates, not measurements, and the app says so next to every one:

The counter in the toolbar totals the session. The saving repeats, too: a document is re-sent on every chat submission, so what a conversion saves once, it saves on every turn of every conversation that uses it. (RAG works differently — the document is embedded once and each query sends only the chunks it retrieves.)

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: 4,916 tokens versus 4,901 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.

A second group shows a token count with no comparison at all: EPUB books, images, Outlook messages, notebooks and ZIP archives. There is no standard alternative format to measure those against, so the app says there is no comparison rather than inventing one.

Watch folders

Nominate a folder in Settings ▸ Watch FoldersSettings ▸ Workflow ▸ 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

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

milldown report.pdf -o report.md
milldown report.xlsx --csv -o report.csv
milldown notes.docx --front-matter provenance -o notes.md
milldown --help

URL scheme and Shortcuts

Milldown registers a milldown:// scheme that works from Shortcuts’ Open URLs action, scripts, and launchersscripts, launchers, and anything that can open a URL:

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 barTray icon

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 integrationExplorer integration

Settings reference

⌘,Ctrl+, opens Settings, where every option lives. Options that apply to a single conversion also live in the inspector, so you can change them in context; the two stay in sync.

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%LOCALAPPDATA%\\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

Local files are converted entirely on your MacPC, 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 three 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, and fetching one when you approve it.
3. Verifying your licence key when you activate, and periodically thereafter.

The one exception is opt-in: the Azure services above do send your documents off this computer — to your own Azure resource, under your own endpoint, credentials and Azure agreement. Both are off by default; when they are off, no document leaves the machine, because there is no other code path that sends one.

Licensing

Milldown is free for 7 days with every feature unlocked and no account required. After that a $39 perpetual licence covers up to 3 Macs, for personal and commercial use. A $249 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 — $19/year for a personal licence, $99/year for a Team licence covering all 10 seats. 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.Settings ▸ License. To move a PC off your licence, use Release this device 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.It is stored encrypted with Windows DPAPI, tied to your user account. The trial date is a plain file in your app data — a timestamp is not a secret.

Updates

Milldown ▸ Check for Updates…. Updates are cryptographically signed and verified before installation.Settings ▸ Updates & about ▸ Check for updates. When a new version is available, Download opens it in your browser — run the installer over your existing copy; your documents and settings are kept. 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 ▸ GeneralSettings ▸ Updates & about 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.

Your update period 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 scans & images is on in Options ▸ Output. 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. 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….

The tool ships with the app. If it stopped working, re-run the Milldown installer — it repairs the PATH entry.

Something else

Use the contact form. Including the file type, what you expected, and what you got makes it far quicker to fix.