talent-factory/pdf-to-markdown

PDF to Markdown Converter

Convert PDF documents to structured Markdown with automatic mode selection.

Workflow

When the user requests PDF conversion:

1. Get PDF path - Ask for the PDF file path if not provided
2. Determine mode - Ask user preference or auto-select based on document type
3. Convert - Execute the appropriate conversion method
4. Output - Save Markdown file and report results

Mode Selection

Ask the user which mode to use:

| Mode | Best For | Speed | |------|----------|-------| | fast | Simple text documents, reports | Very fast | | vision | Complex layouts, code, tables, scans | Medium |

Execution

Fast Mode (PyMuPDF)

Run the converter script:

python ${CLAUDE_PLUGIN_ROOT}/skills/pdf-to-markdown/scripts/pdf_converter.py "<pdf_path>" --mode fast

The script outputs:

• <name>.md - Markdown file with extracted text
• <name>_images/ - Extracted images (if any)

Report the result to the user.

Vision Mode (Claude Code Analysis)

Step 1: Convert PDF to page images:

python ${CLAUDE_PLUGIN_ROOT}/skills/pdf-to-markdown/scripts/pdf_converter.py "<pdf_path>" --mode vision [--pages START-END] [--dpi 150]

This creates <name>_pages/ with PNG images.

Step 2: Read each page image using the Read tool and analyze the content.

Step 3: For each page, generate Markdown following these rules:

• Preserve heading hierarchy (# ## ###)
• Format code blocks with language detection (java, python, etc.)
• Convert tables to Markdown table syntax
• Describe images/diagrams as [Image: description]
• Merge multi-column layouts logically into single-column flow
• Apply Swiss German orthography (ß → ss)
• Ignore page numbers and headers/footers unless relevant

Step 4: Combine all pages into a single Markdown file:

# Document Title

<!-- Page 1 -->

[page 1 content]

---

<!-- Page 2 -->

[page 2 content]

Step 5: Write the final Markdown file using the Write tool.

Step 6: Clean up temporary page images (ask user first).

User Interaction Examples

Example 1: Simple Document

User: Convert /Users/me/report.pdf to Markdown

Claude: I will convert the PDF. Which mode do you prefer?
- **fast**: Quick text extraction (for simple documents)
- **vision**: Image analysis (for complex layouts, code, tables)

User: fast

Claude: [Runs script, reports result]
Done! Created:
- /Users/me/report.md
- /Users/me/report_images/ (3 images)

Example 2: Technical Book

User: Convert java-book.pdf to Markdown, contains a lot of code

Claude: Since the document contains code, I recommend vision mode.
Should I convert the entire PDF or only specific pages?

User: Pages 10-30

Claude: [Converts pages to images]
[Reads each page image]
[Generates structured Markdown with code blocks]
[Writes output file]

Done! Created: java-book.md (21 pages)
Should I delete the temporary page images?

Example 3: Direct Invocation

User: /pdf-to-markdown /path/to/document.pdf

Claude: [Asks for mode preference]
[Executes conversion]
[Reports result]

Prerequisites

Ensure dependencies are installed before first use:

# Fast mode
pip install PyMuPDF Pillow --break-system-packages

# Vision mode (additional)
pip install pdf2image --break-system-packages
brew install poppler  # macOS

Options Reference

| Option | Description | Default | |--------|-------------|---------| | --mode fast | PyMuPDF text extraction | Default | | --mode vision | Prepare images for analysis | - | | --pages START-END | Process specific pages | All | | --dpi N | Image resolution | 150 | | --no-images | Skip image extraction (fast) | - | | --use-api | Direct Anthropic API (vision mode) | Off | | --model NAME | Claude model for --use-api calls | claude-opus-4-7 |

Note on --model: The default is claude-opus-4-7 for high-resolution image handling. Set --model claude-sonnet-4-6 for lower-cost runs on simpler documents. Direct API usage (--use-api) bills the user's ANTHROPIC_API_KEY per page.

Special Features

• LaTeX Umlaut Correction: Fixes ¨a → ä, ¨o → ö, ¨u → ü
• Swiss German: Converts ß → ss automatically
• Quote Normalization: Fixes `` and '' → "
• Code Detection: Identifies programming languages in code blocks
• Table Recognition: Converts visual tables to Markdown syntax