MarkItDown Media-to-Markdown
A set of Terminal commands I built for myself on top of Microsoft's MarkItDown, Tesseract OCR, and Whisper. Drag any file or folder into Terminal and it converts everything to clean Markdown, saved to the Desktop — locally, offline, no AI tokens spent.
Role
Solo designer + builder
Type
Personal productivity tool (future app)
Timeline
July 2026 – present (ongoing)
Tools
MarkItDown, Tesseract, ocrmypdf, Whisper, zsh, Claude
Problem
When I use Claude and other AI tools, images, videos, PDFs, and other media files cost a lot of tokens — and the AI doesn't always read them well.
My main use case: I study IT at a distance-learning university, and my course material arrives as slide screenshots, scanned PDFs, Office files, and recordings. Feeding all of that straight into an AI chat is slow and expensive.
Insight
Through my own research and testing, I learned that converting media to Markdown before importing it into AI saves tokens and helps the AI understand the content better.
And if the conversion runs locally on my Mac, it uses zero Claude/AI tokens at all. This is my own experience from testing, not a published benchmark — I'm not attaching numbers to it.
User & constraints
- One user: me. A designer who reads HTML/CSS but doesn't code.
- Mac only, tight budget — free or low-cost tools only.
- Has to work by dragging a file or folder straight into Terminal.
- No dependency on a paid cloud OCR or transcription service.
Solution
One command per job, all defined in a single shell profile file. Drag a file or folder into Terminal and everything converts and saves to the Desktop.
- A dedicated command per job — plain files, scanned PDFs, single images, image folders, audio/video.
- One "mixed folder" command that routes each file by type automatically.
- Scanned PDFs fall back to an OCR step automatically instead of producing an empty file.
- Every result lands in the same predictable place: the Desktop.
Placeholder — screenshot of the Terminal command in use (drag-and-drop → conversion output)
Design decisions
Drag-and-drop input
I'm not a developer, so typing out file paths by hand was the first thing to remove. Dragging a file or folder from Finder into Terminal fills in the path automatically — no typing, no risk of a typo breaking the command.
One command per job
Each command does exactly one kind of conversion. A short, specific command name is easier for me to remember and trust than one command with many flags I'd have to look up every time.
One folder command that routes by file type
Real course folders are messy — PDFs, slides, images, and recordings mixed together. One command detects each file's type and sends it down the right path, so I don't have to sort files myself before converting.
Resumable runs
Converting a big folder can take a while, especially with OCR or audio. If I need to stop partway (Ctrl+C), re-running the same command skips the files that already finished — so an interruption never means starting over.
Output always to Desktop
One fixed, predictable save location means I never have to hunt for the result. It's always the first thing I see when I switch to the Desktop.
A cleaner for AI-readability
Raw conversions carry noise — huge gaps of blank lines, leftover quiz UI text, OCR artifacts. A separate cleanup step strips that out so the final file is compact and easy for an AI to actually read.
Placeholder — screenshot of the command cheat sheet
What I learned by testing
MarkItDown cannot read scanned PDFs or plain images — it has no OCR built in. Those need an OCR step first, or the output comes back empty or nearly empty.
I ran OCR on a scanned official notice as a test. The main content and dates stayed correct, but some digits were misread — a street number came out as 57 instead of 37, another as 756 instead of 736, and a handwritten document number turned into garbage. The table structure, the stamp, and the handwriting were all lost in the process.
Placeholder — before/after of the scanned notice vs. its OCR'd Markdown
The rule I settled on: use Markdown for long study material where getting the gist is enough. Send the original PDF straight to Claude when exact numbers, tables, or stamps matter.
Iterations
- 01
Terminal opened in the wrong shell
A Markdown code block got pasted directly into my shell profile file, which broke how Terminal opened. Fixed by installing the file with a copy command (cp) instead of pasting content into it directly.
- 02
Images sorted 1, 10, 2 instead of 1, 2, 10
Default alphabetical sort reordered screenshots out of lecture order. Fixed by switching to a numeric sort so filenames sort the way a human would expect.
- 03
Raw OCR output was noisy
Early OCR'd files had huge blank-line gaps and leftover quiz UI text mixed into the content. That's what led to building the separate cleanup command.
Results
A 46-screenshot lecture folder became one single Markdown file in one pass.
After the cleanup step, that file went from 836 lines down to 397 lines — while keeping all 22 "Đáp án" (answer) lines intact.
TODO(Quang): add time-saved / adoption numbers once I'm tracking them.
Next steps / vision
Turn this Terminal tool into a real app — first for macOS, later for iOS — keeping the same drag-and-drop idea but without needing Terminal at all.
- Better Vietnamese OCR accuracy.
- Keep table structure for scanned forms instead of losing it.
This is a plan, not something already built.
