pdf-to-markdown

Run the pdf_to_md.py script with the PDF path as an argument, and it writes a Markdown file next to the source. It uses pymupdf4llm to preserve headers, formatting, lists, and tables, and extracts images into an images folder.

For simple tables, PyMuPDF's text-based table strategy is fast and effective. For complex, borderless, or merged-cell tables, use the --docling flag, which runs IBM's TableFormer AI model for higher accuracy at roughly one second per page.

PyMuPDF is the default fast mode and handles most documents instantly. Docling is slower and downloads about 500MB of AI models on first run, but produces better results for complex tables and higher-resolution images.

Scanned PDFs contain images rather than text layers, so standard extraction yields little text. The documentation recommends installing Tesseract OCR (brew install tesseract) to handle scanned content.

Results are cached in ~/.cache/pdf-to-markdown/ keyed by file content hash and extraction mode. The first extraction does the full work; subsequent runs load from cache unless the PDF changes or you pass --clear-cache.

The skill uses a dedicated virtual environment that may not exist yet. Recreate it with uv venv .venv followed by uv pip install of pymupdf and pymupdf4llm inside the skill directory, as shown in the troubleshooting section.