convert-docs

Convert documents (pdf, docx, pptx, xlsx, and more) to Markdown via markitdown. Point it at a folder and it recursively converts everything, mirroring the structure into a destination folder; point it at a single file and it converts just that file.

Install

Requires Python 3.10+.

uv tool install convert-docs

Don't have uv? Install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows

Or skip uv entirely and use pip: pip install convert-docs

Usage

Run with no flags for an interactive prompt (asks for source, then destination):

convert-docs

Tip (macOS): select a file or folder in Finder and press Option+Command+C to copy its full path, then paste it into the prompt.

Pointing it at a single file converts just that file, writing the .md next to it by default. To use a different output name, append a comma and the new name at the source prompt: ~/Downloads/Report.pdf, quarterly-summary writes quarterly-summary.md.

Or pass flags to skip the prompts:

convert-docs -s ~/Documents/Reports -o ~/Documents/Reports_MD
convert-docs -e pdf,docx        # restrict which extensions get converted
convert-docs -f                 # force re-conversion, ignoring the up-to-date skip
convert-docs --last             # re-run with the same source/destination/extensions as last time
convert-docs -j 8                # convert 8 files in parallel instead of the default 4
convert-docs -n                  # dry run: show what would happen, write nothing

Files with unsupported extensions are listed at the end instead of being silently skipped, and any conversion failures are reported with the underlying error. Common noise directories (.git, node_modules, .venv, __pycache__, etc.) are skipped automatically. If two source files would produce the same output path (e.g. report.docx and report.pdf both map to report.md), the first is converted and the rest are reported as collisions rather than silently overwritten.

Paths are highlighted in supported terminals; set NO_COLOR=1 to disable.

Re-running on new files

Every run saves its source/destination/extensions to ~/.config/convert-docs/last_run.json. Since conversion already skips files whose output is up to date, convert-docs --last is a cheap way to pick up newly added files in a folder you've converted before — run it manually whenever you want to sync, or wire it into a cron job / scheduled task on whatever interval suits you (just point it at the tool's full path, e.g. ~/.local/bin/convert-docs --last, since scheduled jobs don't load your shell profile).

Update

uv tool upgrade convert-docs

Development

uv run pytest