Convert PDF to Markdown using Google Gemini. Built for academic papers and textbooks with heavy math.
Most PDF-to-Markdown tools rely on OCR or layout analysis, which butcher mathematical notation. gemmd takes a different approach: it feeds PDF pages directly to Gemini's multimodal model, which reads the document like a human would — understanding structure, math, and context all at once.
Designed for:
- Research papers with LaTeX-heavy equations
- Textbooks with theorems, proofs, and definitions
- Any PDF where math fidelity matters
Key features:
- Inline (
$...$) and block ($$...$$) math preservation with\tag{}numbering - Concurrent chunk processing with correct ordering
- Smart sentence-boundary merging across page breaks
- Batch mode — convert an entire folder in one command
- Graceful partial failure handling (failed chunks get visible markers, not silent drops)
- Post-conversion verification (page coverage + PDF outline section check)
- Academic post-processing: theorem/lemma normalization, duplicate heading removal, notation cleanup
- Cross-platform: works on macOS, Linux, and Windows
Requirements: Python >= 3.9
pip install gemmdOr install from source:
git clone https://github.com/Kt-L/gemmd.git
cd gemmd
pip install -e .gemmd requires a Google Gemini API key. Get one for free at Google AI Studio.
Quick start (interactive):
gemmd setupThis will prompt you for your API key and preferred default model, then save to ~/.config/gemmd/config.
Or configure individually:
gemmd config key YOUR_API_KEY # set API key
gemmd config model gemini-2.5-pro # set default model
gemmd config # view current configYou can also use environment variables (GEMINI_API_KEY, GEMMD_MODEL) or a .env file in your working directory.
| Setting | Flag | Env / Config key | Default |
|---|---|---|---|
| Model | --model |
GEMMD_MODEL |
gemini-2.5-flash |
| API Key | — | GEMINI_API_KEY |
— |
Priority: CLI flags > local .env > ~/.config/gemmd/config > defaults.
gemmd paper.pdf # → paper.md
gemmd paper.pdf -o notes.md # custom output path
gemmd paper.pdf -m gemini-2.5-pro # use a different model
gemmd paper.pdf --chunk-size 5 # 5 pages per chunk (default: 3)
gemmd paper.pdf -c 10 # limit to 10 concurrent requestsRun gemmd with no arguments to convert all PDFs in the current directory:
cd ~/papers
gemmd- Skips files that already have a corresponding
.md - Continues on failure — check output files for
[!!! MISSING CONTENT !!!]markers
gemmd --list-models| Flag | Short | Default | Description |
|---|---|---|---|
--output |
-o |
<input>.md |
Output file path |
--model |
-m |
gemini-2.5-flash |
Gemini model to use |
--concurrency |
-c |
20 |
Max concurrent API requests |
--chunk-size |
3 |
Pages per chunk | |
--list-models |
List available Gemini models and exit |
| Command | Description |
|---|---|
gemmd setup |
Interactive first-time configuration |
gemmd config |
View current configuration |
gemmd config key <KEY> |
Set API key |
gemmd config model <MODEL> |
Set default model |
- Split — PDF is divided into chunks (default: 3 pages each)
- Transcribe — Chunks are uploaded to Gemini concurrently with a carefully tuned prompt for academic content
- Merge — Results are reassembled in order with intelligent sentence-boundary detection
- Post-process — Regex pipeline normalizes theorems, deduplicates headings, fixes LaTeX artifacts
- Verify — Page coverage check + PDF outline cross-reference to detect missing sections
If any chunks fail (rate limits, timeouts, etc.), gemmd inserts visible [!!! MISSING CONTENT !!!] markers and exits with code 1, so you can re-run to fill gaps.
Using gemini-2.5-flash (default), converting a typical 30-page paper costs fractions of a cent. The Gemini API free tier is generous enough for most personal/research use.
MIT