Skip to content
Back to skills

Mistral Pdf To Markdown

ASecurity

Convert PDFs to Markdown with Mistral OCR and extracted images. Use for scanned PDFs or complex layouts where structured text or images matter.

  • 12 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added September 9, 2026
toolspythonbashgitapi

Works with

  • api

Security analysis

A100/100

Pro scans all 5 files and shows the line behind each finding

Scanned September 9, 2026

npx -y skills add FuZhiyu/superRA --skill mistral-pdf-to-markdown --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Mistral Pdf To Markdown?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Mistral Pdf To Markdown
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fuzhiyu-mistral-pdf-to-markdown/badge)](https://www.skillsdirectory.com/skills/fuzhiyu-mistral-pdf-to-markdown)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: mistral-pdf-to-markdown
description: Convert PDFs to Markdown with Mistral OCR and extracted images. Use for scanned PDFs or complex layouts where structured text or images matter.
user-invocable: true
---

# Mistral PDF to Markdown Converter

Convert PDF documents to Markdown via Mistral's OCR API, preserving headers and structure and extracting embedded images. OCR makes it work on scanned, image-based PDFs.

## Quick Start

`<skill-dir>` in the commands below is the directory containing this `SKILL.md` — substitute the real path.

```bash
# Convert entire PDF
uv run --script <skill-dir>/scripts/convert_pdf_to_markdown.py input.pdf output.md

# Convert specific pages
uv run --script <skill-dir>/scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1-5"
uv run --script <skill-dir>/scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1,3,5"
```

## Output Structure

Each conversion is a self-contained folder. Passing `Output/PDFConversions/paper_alpha.md` creates `Output/PDFConversions/paper_alpha/paper_alpha.md`, with extracted images beside it under `images/` as JPEGs, referenced relatively:

```
Output/PDFConversions/
├── paper_alpha/
│   ├── paper_alpha.md   # references images/img-N.jpeg
│   └── images/
│       ├── img-0.jpeg
│       └── img-1.jpeg
└── paper_beta/
    ├── paper_beta.md
    └── images/
        ├── img-0.jpeg
        └── ...
```

An existing foldered markdown path such as `Output/PDFConversions/paper_alpha/paper_alpha.md` is kept as given. A directory creates `<directory>/<input-pdf-stem>.md`.

## Usage in Code

```python
from pathlib import Path
import subprocess

# Run conversion script
result = subprocess.run([
    "uv", "run", "--script",
    "<skill-dir>/scripts/convert_pdf_to_markdown.py",
    "input.pdf",
    "Output/PDFConversions/output.md",
    "--pages", "1-10"
], capture_output=True, text=True)

print(result.stdout)
```

## Requirements

A Mistral API key (below), plus `mistralai`, `python-dotenv`, `pypdf`, and `pyyaml` — declared inline in the script's PEP 723 header.

## API Key Setup

The script checks these locations in order (first match wins):

1. **Environment variable** `MISTRAL_API_KEY` — recommended for personal use (e.g. `export MISTRAL_API_KEY=your-key` in `secrets.sh`)
2. **Shared config** — `.claude/agent-contract.yaml` or `~/.config/agent-contract/config.yaml` under `paper-reader.mistral_api_key`
3. **`Notes/.env`** — add `MISTRAL_API_KEY=your-key`; gitignored but Dropbox-synced, so it travels with a shared project folder

> **Never commit API keys to git.** Use environment variables or Dropbox-synced `Notes/.env` instead.

## Error Handling

**API Key Not Found:**
```
Error: Mistral API key not found
```
→ Configure it per **API Key Setup** above

**Page Out of Range:**
```
Warning: Page 100 out of range, skipping
```
→ Check the PDF page count and adjust the page selection

**API Rate Limit:**
→ Retry after a moment, or reduce the page count per request

## Notes

- Large PDFs take longer — API limits apply. Narrow with `--pages`.
- Use the `pdf` skill instead for local manipulation and plain text extraction with no OCR or API calls.
- Load [`references/reference.md`](references/reference.md) for the OCR API surface, programmatic and batch usage, cost, and troubleshooting.

Files in this skill

  • SKILL.md3.3 KB
  • references/reference.md6.4 KB
  • scripts/_config_loader.py2.9 KB
  • scripts/convert_pdf_to_markdown.py8.6 KB
  • scripts/test_image_namespacing.py7 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in tools →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.