Claude pdf-to-markdown skill: 10 PDF-to-MD pipelines that just work

The prompt

Convert `papers/q1-report.pdf` to Markdown using the pdf-to-markdown skill. Use the default fast mode (pymupdf4llm). Write the output to `out/q1-report.md` and place any extracted images in `out/q1-report.images/` with relative paths in the markdown. If a table fails to render as a Markdown table, retry that page in accurate mode (docling) and merge it back in. Confirm tables render in Markdown preview before returning.

What slides.md looks like

import pymupdf4llm
from pathlib import Path

src = Path('papers/q1-report.pdf')
out_md = Path('out/q1-report.md')
out_imgs = Path('out/q1-report.images')
out_imgs.mkdir(parents=True, exist_ok=True)

md = pymupdf4llm.to_markdown(
    str(src),
    write_images=True,
    image_path=str(out_imgs),
    image_format='png',
)
out_md.write_text(md, encoding='utf-8')

Pairs with

The prompt

Convert `papers/attention-is-all-you-need.pdf` to Markdown. The PDF is a NeurIPS-style two-column layout with footnotes. Use pdf-to-markdown's accurate mode (docling) so the column reading order is preserved and footnotes land at the end of each section, not mid-paragraph. Strip the running header and page numbers. Save to `out/attention.md` and print the first H2 to stdout so I can sanity-check the section boundaries.

What slides.md looks like

from docling.document_converter import DocumentConverter
from pathlib import Path

src = 'papers/attention-is-all-you-need.pdf'
conv = DocumentConverter()
result = conv.convert(src)
md = result.document.export_to_markdown()

# Strip running header and page numbers (heuristic).
lines = [l for l in md.splitlines()
         if not l.strip().startswith('Page ') and l.strip() != 'Attention Is All You Need']
Path('out/attention.md').write_text('\n'.join(lines), encoding='utf-8')

Pairs with

The prompt

Convert `decks/series-b-update.pdf` to Markdown. Extract every embedded image at full resolution (no downscaling), cache them under `out/series-b-update.images/`, and embed each one inline with a stable filename (`fig-{page}-{idx}.png`). Add a one-line caption above each image based on the surrounding text. Verify the markdown renders on GitHub by previewing the first three image references.

What slides.md looks like

import pymupdf4llm

md_text = pymupdf4llm.to_markdown(
    'decks/series-b-update.pdf',
    write_images=True,
    image_path='out/series-b-update.images',
    image_format='png',
    dpi=200,
    embed_images=False,  # write to disk, reference by relative path
)
# Stable filenames: pymupdf4llm writes 'page-N-image-K.png'.
open('out/series-b-update.md', 'w', encoding='utf-8').write(md_text)

Pairs with

The prompt

Build a RAG ingestion script. Walk `corpus/*.pdf`, convert each via pdf-to-markdown (fast mode), split the markdown at every H2 boundary into chunks (each chunk includes its parent H1 as context), and write to a local Chroma collection named `papers`. Use OpenAI text-embedding-3-small. Skip files where the cache key matches a previous run. Print one line per file: `<name> <chunks> <ms>`.

What slides.md looks like

import pymupdf4llm, re, hashlib, time, chromadb
from pathlib import Path

client = chromadb.PersistentClient('./chroma')
col = client.get_or_create_collection('papers')

for pdf in Path('corpus').glob('*.pdf'):
    t = time.time()
    md = pymupdf4llm.to_markdown(str(pdf))
    chunks = re.split(r'(?m)^## ', md)
    ids = [hashlib.md5(f'{pdf.stem}-{i}'.encode()).hexdigest() for i in range(len(chunks))]
    col.upsert(ids=ids, documents=chunks,
               metadatas=[{'source': pdf.name, 'chunk': i} for i in range(len(chunks))])
    print(f'{pdf.name} {len(chunks)} {int((time.time()-t)*1000)}ms')

Pairs with

The prompt

Open `contracts/msa-redlined.pdf`. Use the pdf-to-markdown skill (fast mode), then post-process: walk every highlight annotation in the PDF (PyMuPDF exposes `page.annots()` with `type[0] == 8` for highlight), capture the highlighted text plus the sentence it sits inside, and emit each as a Markdown blockquote with a `> [!NOTE]` callout block. Save to `out/msa-redlined-highlights.md`.

What slides.md looks like

import pymupdf

doc = pymupdf.open('contracts/msa-redlined.pdf')
out = []
for page_num, page in enumerate(doc, 1):
    for annot in page.annots() or []:
        if annot.type[0] == 8:  # highlight
            quad = annot.vertices
            text = page.get_textbox(annot.rect)
            out.append(f'> [!NOTE] page {page_num}\n> {text.strip()}\n')
open('out/msa-redlined-highlights.md', 'w').write('\n'.join(out))

Pairs with

The prompt

Convert `archive/1998-financial-report.pdf` to Markdown. The file is scanned (no text layer). Detect that automatically by checking page 1 with `page.get_text()` — if it returns less than 50 chars, fall back to OCR via pytesseract. Use `lang='eng'`. Cache OCR results under `~/.cache/pdf-to-markdown/` so re-runs skip re-OCR. Save the markdown to `out/1998-financial-report.md` and warn me if OCR confidence dips below 60%.

What slides.md looks like

import pymupdf, pytesseract
from PIL import Image
from io import BytesIO
from pathlib import Path

doc = pymupdf.open('archive/1998-financial-report.pdf')
md = []
for i, page in enumerate(doc):
    text = page.get_text().strip()
    if len(text) < 50:
        pix = page.get_pixmap(dpi=300)
        img = Image.open(BytesIO(pix.tobytes('png')))
        text = pytesseract.image_to_string(img, lang='eng')
    md.append(f'## Page {i+1}\n\n{text}\n')
Path('out/1998-financial-report.md').write_text('\n'.join(md), encoding='utf-8')

Pairs with

The prompt

Walk `vendor-docs/**/*.pdf` recursively. For each PDF, convert to Markdown using pdf-to-markdown (fast mode) and write to `markdown-out/<same relative path>.md`. Use a content hash as the cache key so re-runs only re-process files whose bytes changed. Run 4 conversions in parallel via `concurrent.futures.ProcessPoolExecutor`. Print a final summary: total PDFs, converted, skipped (cache hit), failed.

What slides.md looks like

import pymupdf4llm, hashlib
from pathlib import Path
from concurrent.futures import ProcessPoolExecutor, as_completed

CACHE = Path.home() / '.cache/pdf-to-markdown'
CACHE.mkdir(parents=True, exist_ok=True)

def convert(pdf):
    h = hashlib.sha1(pdf.read_bytes()).hexdigest()[:16]
    cache_hit = (CACHE / f'{h}.md')
    if cache_hit.exists():
        return (pdf, 'skip')
    md = pymupdf4llm.to_markdown(str(pdf))
    cache_hit.write_text(md, encoding='utf-8')
    out = Path('markdown-out') / pdf.relative_to('vendor-docs').with_suffix('.md')
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(md, encoding='utf-8')
    return (pdf, 'ok')

pdfs = list(Path('vendor-docs').rglob('*.pdf'))
with ProcessPoolExecutor(max_workers=4) as ex:
    for f in as_completed([ex.submit(convert, p) for p in pdfs]):
        print(*f.result())

Pairs with

The prompt

Open `papers/transformer-survey.pdf`. Convert it to Markdown with pdf-to-markdown, then slice out only the section starting from the heading 'References' (case-insensitive) through end-of-document. Normalize each entry to a single line, strip line-wrap hyphens, and write to `out/transformer-survey.refs.md` as a numbered list.

What slides.md looks like

import pymupdf4llm, re
from pathlib import Path

md = pymupdf4llm.to_markdown('papers/transformer-survey.pdf')
m = re.search(r'(?im)^#+\s*references\s*$', md)
if not m:
    raise SystemExit('No References section found')
refs = md[m.end():]
# Collapse line wraps and strip soft hyphens.
refs = re.sub(r'-\n', '', refs)
refs = re.sub(r'\n(?!\[)', ' ', refs)
entries = re.findall(r'\[\d+\][^\[]+', refs)
out = '\n'.join(f'{i+1}. {e.strip()}' for i, e in enumerate(entries))
Path('out/transformer-survey.refs.md').write_text(out, encoding='utf-8')

Pairs with

The prompt

Open `filings/10K-2025.pdf`. Use pdf-to-markdown's accurate mode to extract every table on pages 30-60. For each table, write a Markdown table to `out/10K-tables.md` AND a parallel CSV under `out/csv/table-{page}-{idx}.csv`. Add a one-line index at the top of `10K-tables.md` linking each table to its CSV. Skip any table with fewer than 2 columns or 2 rows.

What slides.md looks like

import pandas as pd
from docling.document_converter import DocumentConverter
from pathlib import Path

Path('out/csv').mkdir(parents=True, exist_ok=True)
result = DocumentConverter().convert('filings/10K-2025.pdf', page_range=(30, 60))
md_lines = ['# 10-K tables\n']
for i, table in enumerate(result.document.tables):
    df = table.export_to_dataframe()
    if df.shape[0] < 2 or df.shape[1] < 2:
        continue
    csv_name = f'table-{table.prov[0].page_no}-{i}.csv'
    df.to_csv(f'out/csv/{csv_name}', index=False)
    md_lines.append(f'## Table {i} (p.{table.prov[0].page_no}) [{csv_name}](csv/{csv_name})\n')
    md_lines.append(df.to_markdown(index=False))
Path('out/10K-tables.md').write_text('\n\n'.join(md_lines), encoding='utf-8')

Pairs with

The prompt

Convert `contracts/msa-2024.pdf` and `contracts/msa-2025.pdf` to Markdown using pdf-to-markdown (fast mode). Strip page numbers and running headers from both before diffing — they create false positives. Run `git diff --no-index --word-diff=color msa-2024.md msa-2025.md` and write the diff to `out/msa-diff.md` with a header summarizing how many lines added/removed.

What slides.md looks like

import pymupdf4llm, re, subprocess
from pathlib import Path

def clean(p):
    md = pymupdf4llm.to_markdown(p)
    md = re.sub(r'(?m)^\s*Page \d+ of \d+\s*$', '', md)
    return md

a = Path('out/msa-2024.md'); a.write_text(clean('contracts/msa-2024.pdf'))
b = Path('out/msa-2025.md'); b.write_text(clean('contracts/msa-2025.pdf'))
r = subprocess.run(['git', 'diff', '--no-index', '--word-diff=plain', str(a), str(b)],
                   capture_output=True, text=True)
Path('out/msa-diff.md').write_text(f'# MSA diff 2024 -> 2025\n\n\u0060\u0060\u0060diff\n{r.stdout}\n\u0060\u0060\u0060')

Pairs with