Markitdown CLI — Development skill for Claude Code

markitdown

A personal `mdc` CLI that wraps Microsoft's markitdown library with recursive directory conversion, mtime-based skip caching, and optional OpenAI image OCR and Whisper audio transcription.

**Not Microsoft's project.** This repo is Eric's thin wrapper *around* [microsoft/markitdown](https://github.com/microsoft/markitdown), which does the actual document parsing (pulled in as the `markitdown[all]` dependency). The package is published locally as `markitdown-cli`; all credit for the conversion engine goes upstream. Remote: `github.com/BaruchEric/markitdown-cli`.

TL;DR

• What: mdc — convert documents (PDF, Office, HTML, images, audio, …) to Markdown, one file or a whole tree.
• How: delegates parsing to Microsoft's markitdown; adds the CLI ergonomics — recursive walking, mirrored output layout, mtime-based skip, per-file error aggregation, meaningful exit codes.
• Optional AI: --ocr describes images via OpenAI gpt-4o-mini; --audio transcribes audio via the Whisper API (whisper-1). Plain conversions need no API key.
• Stack: Python ≥ 3.11, uv-managed, hatchling build, pytest (12 tests); deps: markitdown[all], openai, python-dotenv.
• Run: uv tool install . → mdc notes.pdf or mdc ~/Documents/papers -o ~/md.
• A companion markitdown Claude skill calls mdc automatically when Claude Code hits a file it can't read directly.

Overview

`mdc` is a single-purpose disk utility for turning non-text files into Markdown. It hands the actual parsing to Microsoft's `markitdown` library and layers on what a batch CLI needs:

• Single file or recursive tree. Point it at a file or a directory; a directory is walked recursively (rglob) and the output mirrors the source layout.
• Skip-if-up-to-date. A target .md whose mtime is newer than (or equal to) its source is left untouched unless --force is passed, so re-running over a large folder only reconverts what changed.
• **Batch-tolerant.