pdf-to-md

Converts PDF files into structured Markdown using pymupdf4llm with table and image preservation.

Updated Jul 7, 2026
One-click install
npx skills add https://github.com/hivgb1-ai/do-better-workspace-v2 --skill pdf-to-md-hivgb1-ai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: pdf-to-md
Source: https://github.com/hivgb1-ai/do-better-workspace-v2/tree/main/.claude/skills/pdf-to-md
Command: npx skills add https://github.com/hivgb1-ai/do-better-workspace-v2 --skill pdf-to-md-hivgb1-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pymupdf4llm, and includes scripts (resource) components.

What problem does it solve? Reading PDFs through an AI's built-in file reader consumes large amounts of context tokens and often loses tables, headings, and layout structure. This Skill converts PDFs into clean, LLM-friendly Markdown offline via a script, so large documents are processed without consuming tokens and with layout preserved. ## Core Features & Use Cases - Layout-preserving conversion: Uses pymupdf4llm to keep tables, headings, multi-column order, and image links intact in the Markdown output. - Selective processing: Convert specific page ranges (e.g., 1-5 or 1,3,5-10) and optionally extract embedded images as PNG files into a companion folder. - Scan detection: The --info mode reports page count, size, and text density, warning when a PDF is image-based and needs OCR instead. - Use Case: You receive a 100-page research report PDF. Run the converter to get a structured Markdown file, preview the first lines, then file it into your knowledge base or feed it to a wiki-ingest workflow. ## Quick Start Ask the AI to convert a specific PDF file to Markdown, optionally mentioning a page range or that you want the images extracted too.

Frequently Asked Questions about pdf-to-md

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a PDF to Markdown in Python?

Use pymupdf4llm's to_markdown function, which converts PDF pages into Markdown while preserving tables, headings, and image references. This Skill wraps that call in a CLI script supporting page ranges, output paths, and image extraction.

What is the best tool for converting PDF to Markdown for LLMs?

pymupdf4llm is designed for LLM-friendly Markdown output, preserving tables and heading structure. For math-heavy papers, marker-pdf may handle LaTeX better, and for table-heavy files, pdfplumber is a specialized alternative.

Can pymupdf4llm convert scanned PDF documents?

No, pymupdf4llm extracts embedded text only and cannot read scanned image pages. The script detects likely scan PDFs by sampling text density and warns you to use OCR tools like tesseract or Gemini Vision instead.

How do I convert only specific pages of a PDF?

Pass a page range such as 1-5 or a mixed list like 1,3,5-10 to the --pages option. The script parses the range, clamps it to the document length, and converts only those pages.

Why does pip install pymupdf4llm fail with a PEP 668 error?

Python 3.12+ and Homebrew Python block system-wide pip installs. Create a virtual environment with python3 -m venv .venv, activate it, then install pymupdf4llm inside that environment.