pdf-to-markdown-converter

使用 PyMuPDF 将 PDF 文件转换为 Markdown 格式,提取文本内容和嵌入的图像。快速且轻量级。自动修复 LaTeX 变音符号(¨a → ä 等)并将 ß 转换为 ss(德语)。在将 PDF 转换为 Markdown、提取文档内容或处理 PDF 文件进行文本分析时使用。生成一个 .md 文件和 0..n 个 .png 图像文件。

📖 中文导读:使用 PyMuPDF 将 PDF 文件转换为 Markdown 格式,提取文本内容和嵌入的图像。快速且轻量级。自动修复 LaTeX 变音符号(¨a → ä 等)并将 ß 转换为 ss(德语)。在将 PDF 转换为 Markdown、提取文档内容或处理 PDF 文件进行文本分析时使用。生成一个 .md 文件和 0..n 个 .png 图像文件。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: pdf-to-markdown-converter description: Converts PDF files to Markdown format using PyMuPDF, extracting text content and embedded images. Fast and lightweight. Automatically fixes LaTeX umlauts (¨a → ä, etc.) and converts ß to ss (Swiss German). Use when converting PDFs to Markdown, extracting document content, or processing PDF files for text analysis. Generates one .md file and 0..n .png files for images.

PDF to Markdown Converter

Overview

This skill converts PDF files to Markdown format using the PyMuPDF (fitz) library. It extracts text content and saves embedded images as separate PNG files. This is a fast and lightweight alternative to Docling.

Special Features:

  • ✅ Automatically fixes LaTeX-style umlauts (¨a, ¨o, ¨u → ä, ö, ü)
  • ✅ Converts ß to ss (Swiss German style)
  • ✅ Corrects common LaTeX encoding issues
  • ✅ Preserves text layout
  • ✅ Extracts all images as PNG files

Prerequisites

Ensure PyMuPDF is installed (installs in ~10-20 seconds):

pip install PyMuPDF --break-system-packages

Optional for better image format support:

pip install Pillow --break-system-packages

Usage Workflow

  1. Receive PDF file: User provides the PDF file path
  2. Validate input: Check that the file exists and is a valid PDF
  3. Run conversion: Execute pdf_converter.py with the PDF path
  4. Output organization:
    • Markdown file: <original_name>.md
    • Images folder: <original_name>_images/ containing PNG files
    • Images are referenced in the Markdown with relative paths

Conversion Command

python scripts/pdf_converter.py <input.pdf> [output_dir]

Parameters:

  • input.pdf: Path to the source PDF file
  • output_dir: (Optional) Output directory. Defaults to current directory

Output Structure

output_dir/
├── document.md              # Converted markdown content
└── document_images/         # Extracted images (if any)
    ├── image_001.png
    ├── image_002.png
    └── ...

Error Handling

If conversion fails:

  • Check PDF is not corrupted or password-protected
  • Verify Docling installation
  • Ensure sufficient disk space for image extraction
  • Review console output for specific error messages

Best Practices

  • Large PDFs may take time to process - inform user
  • Preview the first page for complex documents to verify quality
  • For batch processing, process files sequentially to avoid memory issues
  • Preserve original PDF files - never overwrite source documents