pdf-to-md

name

pdf-to-md

description

Zero-dependency PDF to Markdown converter — no Python venvs, no AI model downloads, works offline out of the box. Uses Claude's native Read tool for visual structure recognition and poppler's pdfimages for lossless figure extraction. Use this skill whenever the user wants to convert a PDF to Markdown (.md), extract text from a PDF into Markdown format, or mentions "PDF to MD", "PDF to markdown", "PDF 转 md", "把 PDF 转成 markdown". Also trigger when the user has a PDF (paper, report, proposal, manual, specification) and wants a readable markdown version. Handles academic papers, technical reports, proposals, manuals, and general documents up to ~100 pages. Do NOT use for: filling PDF forms, merging/splitting PDFs, creating new PDFs, or extracting images/tables to separate files — use the `pdf` skill for those tasks.

PDF to Markdown Conversion

Convert PDF documents into clean, well-structured Markdown while preserving semantic structure — headings, lists, tables, figures, equations, and references.

Prerequisites

• poppler (for image extraction): brew install poppler (macOS) or apt install poppler-utils (Linux)
  • Provides pdfimages and pdftoppm commands
  • Skip if the PDF has no figures

No Python packages, virtual environments, or AI model downloads required.

Strategy

The workflow uses Claude's Read tool to view the PDF visually, then structures the markdown with full awareness of the document layout. Images are extracted losslessly using pdfimages from poppler. This approach is:

• Zero-config — no venvs, no pip installs, no model downloads
• Offline — works without network access
• Accurate — Claude sees the actual rendered pages, not lossy text extraction

Workflow

Step 1: Locate the PDF

Use Glob to find the file if the user gives a partial name or description.

Step 2: Read the PDF and extract images (in parallel)

Run these two operations simultaneously:

Read the PDF using the Read tool with the pages parameter:

Read(file_path="...", pages="1-20")

For PDFs over 20 pages, read in chunks of 20.

Extract embedded images using pdfimages:

pdfimages -list "input.pdf"                    # Check what's embedded
mkdir -p images && pdfimages -png "input.pdf" images/fig  # Extract all

This extracts figures at their original resolution — no cropping, no guesswork.

If pdfimages finds no embedded images (pure vector diagrams), fall back to rendering the page:

pdftoppm -png -r 200 -f <PAGE> -l <PAGE> "input.pdf" images/page<N>

Then crop using Pillow after visually identifying coordinates via the Read tool.

Text extraction fallback — when Read tool output is hard to parse (complex multi-column layouts):

python3 -c "import pdfplumber" 2>/dev/null || pip3 install pdfplumber -q
python3 -c "
import pdfplumber
with pdfplumber.open('file.pdf') as pdf:
    for i, page in enumerate(pdf.pages):
        print(f'=== PAGE {i+1} ===')
        print(page.extract_text())
"

Step 3: Identify document structure

Scan through the content and identify:

1. Title and authors — usually the first lines, centered or bold
2. Heading hierarchy — map section numbering (1, 1.1, 1.1.1) to markdown levels (#, ##, ###)
3. Body paragraphs — merge lines broken by PDF line wrapping into flowing paragraphs
4. Numbered/bulleted lists — convert to markdown list syntax
5. Tables — convert to markdown table syntax with | and alignment
6. Figures/diagrams — rename extracted images descriptively and note placement
7. References/bibliography — preserve numbering and hyperlinks
8. Footnotes — integrate inline or collect at section end

Step 4: Write the Markdown file

Save with the same base filename and .md extension, in the same directory as the source PDF.

Structure mapping:

PDF element	Markdown output
Document title	# Title
Author(s)	**Author Name** on its own line
Abstract	## Abstract section
Top-level section (1, 2, 3...)	## Section Name
Subsection (1.1, 2.1...)	### Subsection Name
Sub-subsection (1.1.1...)	#### Sub-subsection Name
Numbered list items	1., 2., 3.
Bullet points	- items
Table	Markdown table with header row and `
Figure/diagram	
Inline citation [N]	[N] preserved as-is
Reference list	Numbered list under ## References
Equations	LaTeX $...$ or $$...$$
Bold/italic	**bold** / *italic*

Key rules:

• Merge PDF line breaks within paragraphs into flowing text
• Merge tables that span multiple pages into one markdown table
• Preserve DOI links and URLs in references
• Convert Gantt charts / timelines into markdown tables
• When in doubt about heading level, prefer deeper (### over ##)

Step 5: Verify output

Quick checks before finishing:

• All sections from the PDF are present
• Heading hierarchy is consistent
• No content dropped
• References complete and numbered correctly
• Images linked and viewable

Output quality standards

• Semantic accuracy over visual fidelity — readable, well-structured markdown
• Keep the original language (don't translate)
• Don't add content not in the PDF
• Don't add commentary unless the user asks