PDF to Markdown Converter

cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf docling docling-core

Verify Installation

~/.claude/skills/pdf-to-markdown/.venv/bin/python -c "import pymupdf; import docling; import docling_core; print('OK')"

Quick Start

# Convert PDF to markdown (always extracts images)
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py document.pdf

# Output: document.md + images/ folder (next to the .md file)

Standard Workflow

When user provides a PDF and wants full content in context:

Step 1: Ensure the skill venv exists

test -d ~/.claude/skills/pdf-to-markdown/.venv || (cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf docling docling-core)

Step 2: Convert PDF to Markdown

~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py "/path/to/document.pdf"

Step 3: Read the output

# Output is written to document.md in the same directory as the PDF
cat /path/to/document.md

Caching

PDFs are aggressively cached to avoid re-processing. First extraction is slow (~1 sec/page), every subsequent request is instant.

How It Works

• Cache location: ~/.cache/pdf-to-markdown/<cache_key>/
• Cache key: Based on file content hash
• Invalidation: Cache is invalidated when:
  • Source PDF is modified (size or mtime changes)
  • Extractor version changes (automatic re-extraction)
  • Explicitly cleared with --clear-cache or --clear-all-cache

Cache Commands

# Clear cache for a specific PDF
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py document.pdf --clear-cache

# Clear entire cache
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py --clear-all-cache

# Show cache statistics
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py --cache-stats

Cache Contents

~/.cache/pdf-to-markdown/<cache_key>/
├── metadata.json    # source path, mtime, size, total_pages
├── full_output.md   # cached full markdown
└── images/          # extracted images

Image Handling

Images are always extracted. They are:

• Cached in ~/.cache/pdf-to-markdown/<cache_key>/images/
• Copied to images/ folder next to the output .md file
• Referenced in the markdown with relative paths (images/filename.png)
• Summarized in a table at the end of the document

Auto-View Behavior for Images

IMPORTANT: When the extracted markdown contains image references like:

**[Image: figure_1.png (1200x800, 125.3KB)]**

And the user asks about something that might be visual (charts, graphs, diagrams, figures, screenshots, layouts, designs, plots, illustrations), automatically use the Read tool to view the relevant image file(s) before answering. Don't ask the user - just look at it.

Examples of when to auto-view images:

• User: "What does the chart on page 3 show?" → Read the image file
• User: "Summarize the figures in this paper" → Read all image files
• User: "What's in the diagram?" → Read the image file
• User: "Describe the architecture shown" → Read the image file
• User: "What are the results?" (and there's a results figure) → Read it

Output Format

The markdown output includes:

Header (metadata)

---