pdf-to-markdown

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:

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