What is mistral-pdf-to-markdown?

This Claude skill leverages the Mistral OCR API to seamlessly convert complex PDF documents, including scanned files, into structured Markdown format. It solves the challenge of manual data entry and formatting loss by automatically extracting text, preserving document hierarchy, and saving embedded images, making it ideal for digitizing research papers and technical documentation.

When should I use mistral-pdf-to-markdown?

mistral-pdf-to-markdown is useful in the following scenarios: • Digitizing Scanned Documents: Convert non-searchable, scanned PDFs into editable and searchable Markdown text using high-accuracy OCR. • Research Paper Management: Transform academic papers into Markdown to easily integrate citations, text, and figures into personal knowledge bases like Obsidian or Notion. • Automated Content Migration: Streamline the process of moving legacy PDF documentation into modern documentation platforms that support Markdown. • Data Extraction for AI Training: Prepare clean, structured text data from complex PDF layouts for fine-tuning LLMs or building RAG (Retrieval-Augmented Generation) systems.

name	mistral-pdf-to-markdown
description	Convert PDFs to Markdown using Mistral OCR API with image extraction. Use when you need to extract structured text and images from PDFs, especially for scanned documents or documents with complex formatting. Outputs Markdown with embedded images.

Mistral PDF to Markdown Converter

Convert PDF documents to Markdown format using Mistral's OCR API. Automatically extracts text, formatting, and images.

When to Use

Converting research papers or documents to Markdown
Extracting text from scanned PDFs (OCR capability)
Preserving document structure with headers and formatting
Extracting embedded images from PDFs

Quick Start

Use the conversion script from this skill's directory:

# Convert entire PDF
python scripts/convert_pdf_to_markdown.py input.pdf output.md

# Convert specific pages
python scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1-5"
python scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1,3,5"

Output Structure

Output/PDFConversions/
├── document.md          # Markdown with text and image references
└── images/
    ├── img-0.jpeg      # Extracted images
    ├── img-1.jpeg
    └── ...

Usage in Code

from pathlib import Path
import subprocess

# Run conversion script
result = subprocess.run([
    "python",
    ".claude/skills/mistral-pdf-to-markdown/scripts/convert_pdf_to_markdown.py",
    "input.pdf",
    "Output/PDFConversions/output.md",
    "--pages", "1-10"
], capture_output=True, text=True)

print(result.stdout)

Key Features

Markdown formatting: Preserves headers, lists, and structure
Image extraction: Saves images to images/ subfolder automatically
Page selection: Extract specific pages or ranges
Scanned PDF support: True OCR capability for image-based PDFs
Relative paths: Image references use ![...](images/img-X.jpeg)

Requirements

The script requires:

Mistral API key in Notes/.env (line 2: mistral_api_key=...)
Python packages: mistralai, python-dotenv, pypdf

Common Use Cases

Convert Research Paper

python scripts/convert_pdf_to_markdown.py \
  "Data/papers/research.pdf" \
  "Notes/Paper Markdown/research.md"

Extract Specific Sections

# Extract pages 10-20 (introduction and methods)
python scripts/convert_pdf_to_markdown.py \
  "paper.pdf" \
  "Notes/Paper Markdown/intro_methods.md" \
  --pages "10-20"

Extract Figures Only

# Extract pages with figures
python scripts/convert_pdf_to_markdown.py \
  "paper.pdf" \
  "Notes/Paper Markdown/figures.md" \
  --pages "25,27,30,35"

Error Handling

API Key Not Found:

Error: Mistral API key not found in Notes/.env

→ Add mistral_api_key=YOUR_KEY to line 2 of Notes/.env

Page Out of Range:

Warning: Page 100 out of range, skipping

→ Check PDF page count and adjust page selection

API Rate Limit: → Wait a moment and retry, or reduce page count per request

Notes

Images are saved as JPEG files in images/ subfolder
Markdown image references are automatically updated to images/img-X.jpeg
Large PDFs may take longer to process due to API limits
For simple text extraction without OCR, consider using the pdf skill instead
Scanned PDFs benefit most from this skill's OCR capability

mistral-pdf-to-markdown

When & Why to Use This Skill

Use Cases