pdf-to-markdown-cli

Simple Python CLI for converting PDF books and documents into Markdown files using pymupdf4llm.

It is designed for local workflows where you want a practical command-line tool that can:

• convert one PDF or a batch of PDFs
• preserve document text structure as Markdown
• optionally extract images
• optionally use OCR for scanned PDFs

Why this exists

Many PDF-to-Markdown workflows are either too heavy, too API-dependent, or too tied to notebook-style experiments. This project wraps pymupdf4llm in a small CLI so you can use it directly from the terminal.

Features

• Convert one PDF or a directory of PDFs
• Optional recursive directory scanning
• Optional page selection
• Optional extracted image output
• OCR flags for scanned PDFs
• Preserves folder structure when converting directories

Requirements

• Python 3.10+
• pymupdf4llm

Optional but useful for scanned PDFs:

• local OCR support used by the backend toolchain

Installation

From source

git clone https://github.com/owezzy/pdf-to-markdown-cli.git
cd pdf-to-markdown-cli
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Then run:

pdfmd --help

Without installing the console script globally

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pdfmd --help

Usage

Convert one PDF

pdfmd "/path/to/book.pdf"

Convert one PDF to a specific file

pdfmd "/path/to/book.pdf" --output "/path/to/output/book.md"

Convert only selected pages

pdfmd "/path/to/book.pdf" --pages "1-10,15,20-22"

Convert a directory of PDFs

pdfmd "/path/to/pdfs" \
  --glob "*.pdf" \
  --output "/path/to/output"

Convert a directory recursively

pdfmd "/path/to/pdfs" \
  --recursive \
  --glob "*.pdf" \
  --output "/path/to/output"

Extract images next to the Markdown file

pdfmd "/path/to/book.pdf" --write-images

This creates something like:

Apollo.md
Apollo_images/

Better handling for scanned PDFs

pdfmd "/path/to/book.pdf" \
  --force-ocr \
  --ocr-language eng

Example options

pdfmd input.pdf \
  --output output.md \
  --pages "1-20" \
  --write-images \
  --page-separators \
  --show-progress

How it works

This CLI uses:

• pymupdf4llm.to_markdown(...) for Markdown extraction
• optional OCR flags for scanned or difficult PDFs
• optional image extraction to a sibling directory

The output is intended to be useful for note-taking, archival, and LLM/RAG preprocessing, but complex PDFs may still need cleanup.

Notes

• OCR quality depends on your local OCR dependencies and the source PDF quality.
• pymupdf4llm is optimized for Markdown extraction, but heavily formatted books may still need cleanup afterward.

Development

Run the CLI locally:

python -m pdfmd --help

Basic syntax check:

python -m py_compile pdfmd/cli.py pdfmd/__main__.py pdfmd/__init__.py

Release process

Release notes and tagging instructions live in:

RELEASING.md

High-level flow:

1. update the version in pyproject.toml
2. push the release commit to main
3. create and push a vX.Y.Z tag
4. create a GitHub release from that tag

Contributing

Issues and pull requests are welcome.

Good contributions include:

• better OCR handling
• metadata extraction
• richer Markdown cleanup options
• better batch conversion output
• packaging improvements

License

MIT

Help

pdfmd --help