pdf-to-markdown

PDF to Markdown

Convert a PDF document to Markdown, detecting its content characteristics and choosing the appropriate extraction method. Extracts text, preserves structure, and saves images to a separate assets directory.

When to use

• Converting a PDF report, paper, or book to Markdown
• Migrating PDF-based documentation to text format
• User specifies a particular extractor preference

Inputs to gather

• PDF file path (required)
• Extractor choice: marker, docling, pymupdf4llm, or pdftotext (optional; defaults from config.json)
• OCR flag: --ocr to force OCR on image-heavy documents (optional)

Procedure

1. Activate the venv at $CLAUDE_USER_DATA/document-to-markdown/venv/.
2. Check if the PDF has a text layer by running pdftotext -layout <pdf> - and examining output length. If minimal/empty, suggest running ocr-scanned-pdf first unless --ocr was passed.
3. Read config.json from $CLAUDE_USER_DATA/document-to-markdown/ to get the default extractor if not specified by the user.
4. Run the chosen extractor:
   • marker: Best for layout-rich, multi-column, or formatted documents (slower, more accurate layout)
   • docling: Modern layout detection; acceptable middle ground (requires setup if not in venv)
   • pymupdf4llm: Fast text extraction; good for text-heavy, simple PDFs
   • pdftotext -layout: Dumb fallback; plain text with best-effort spacing
5. Save output as <stem>.md next to the source PDF, where <stem> is the filename without extension.
6. Extract images to <stem>.assets/ directory alongside the PDF.
7. Provide guidance on extractor selection if the user did not specify one (recommend marker for most documents).

Output / side effects

• <stem>.md file next to the source PDF, containing extracted and formatted text
• <stem>.assets/ directory with any extracted images
• Console output describing what was done and which extractor was used

Safety / constraints

• If no text layer is detected, prompt before proceeding; offer to run OCR first
• Do not overwrite existing output files without asking