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
- Receive PDF file: User provides the PDF file path
- Validate input: Check that the file exists and is a valid PDF
- Run conversion: Execute pdf_converter.py with the PDF path
- Output organization:
- Markdown file:
<original_name>.md - Images folder:
<original_name>_images/containing PNG files - Images are referenced in the Markdown with relative paths
- Markdown file:
Conversion Command
python scripts/pdf_converter.py <input.pdf> [output_dir]
Parameters:
input.pdf: Path to the source PDF fileoutput_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