| name | pdf-to-markdown |
| description | Converts PDF files to structured Markdown with automatic mode selection. Supports simple text extraction (fast) and complex layouts with code/tables (vision). Triggers when the user wants to convert a PDF document, extract PDF content, or transform PDF to Markdown format. |
PDF to Markdown Converter
Convert PDF documents to structured Markdown with automatic mode selection.
Workflow
When the user requests PDF conversion:
- Get PDF path - Ask for the PDF file path if not provided
- Determine mode - Ask user preference or auto-select based on document type
- Convert - Execute the appropriate conversion method
- 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:
pip install PyMuPDF Pillow --break-system-packages
pip install pdf2image --break-system-packages
brew install poppler
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
