pdf-to-md

Writing by hand aligns more naturally with the flow of thought than typing in my mind.

This tool converts handwritten notes to Markdown using AI, designed as a seamless Obsidian Plugin.

中文文档 | English

📖 A little history

While studying control theory, I fell in love with the handwriting experience of the iFlytek Smart Notebook. However, organizing notes in Obsidian proved frustrating: the native OCR was terrible at recognizing mathematical formulas.

I developed this plugin to solve that problem. It leverages powerful Vision Language Models (Qwen-VL, GPT-5.4, and Gemini) to provide:

• Accurate Mixed Recognition: Seamlessly handles text and complex formulas
• LaTeX Math Formulas: Converts equations into clear Obsidian-renderable LaTeX ($...$ and $$...$$)
• Cost-Effective & Flexible: Choose cheap, fast, or ultra-accurate models inside Obsidian

🎉 Obsidian Plugin

An all-in-one Obsidian plugin that converts handwritten PDFs to Markdown in a single click!

Key Features:

• 📄 Right-click any PDF → "Convert to Markdown"
• 📊 Real-time progress tracking with visual progress bar
• 🔐 Secure API key management (read-only environment variables check)
• ⚙️ Configurable DPI, timeout, retry, and file conflict handling
• 🤖 Support
  • GPT
  • Alibaba Qwen (千问)
  • Claude
  • Google Gemini
  • Local LLM (ollama)

Plugin Installation

Method 1: Obsidian Plugin Marketplace (Recommended)

1. Open Obsidian → Settings → Community Plugins
2. Search for "pdf-to-md"
3. Click Install and Enable

Method 2: Manual Installation

1. Download main.js and manifest.json from the latest GitHub Release
2. Copy them into your vault:

   <your-vault>/.obsidian/plugins/pdf-to-md/
   ├── main.js
   └── manifest.json
   

3. Restart Obsidian and enable the plugin

Method 3: Build from Source

1. Clone the repo:

   git clone https://github.com/kkbin505/pdf-to-md.git
   cd pdf-to-md
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Copy the built files into your vault:

   cp main.js manifest.json <your-vault>/.obsidian/plugins/pdf-to-md/
   

4. Restart Obsidian and enable the plugin

Plugin Quick Start

1️⃣ Configure Environment Variables

Important: pdf-to-md reads API keys from environment variables only. No API keys are stored on disk. This is more secure.

Get Your API Keys:

• Alibaba Qwen (Recommended): https://dashscope.console.aliyun.com/apiKey
• OpenAI: https://platform.openai.com/api-keys
• Google Gemini: https://aistudio.google.com/
• Anthropic Claude: https://platform.claude.com/settings/workspaces/default/keys

Set Environment Variables:

Mac/Linux:

# Edit ~/.bashrc or ~/.zshrc (Mac users use ~/.zprofile), add:
export DASHSCOPE_API_KEY='sk-xxx...'
export OPENAI_API_KEY='sk-proj-xxx...'
export GEMINI_API_KEY='AIzaSyxxx...'
export ANTHROPIC_API_KEY='sk-ant-xxx...'

# Save and reload:
source ~/.bashrc  # or source ~/.zshrc

⚠️ Restart Obsidian after setting environment variables (complete restart required, not just reload).

2️⃣ Select AI Provider

Open Obsidian Settings → PDF to Markdown:

• Select the AI model directly from the unified Model dropdown.

3️⃣ Convert PDF/image

1. Find PDF/image in Obsidian file browser
2. Right-click → "Convert to Markdown"
3. Wait for conversion (progress bar shows status)
4. Converted .md file is auto-saved

4️⃣ Convert images embedded in notes (new)

Right-click any image inside an open note → "Convert Image to Markdown". The recognized text and formulas are inserted directly below the image in the same note — no new file is created.

Qwen

GPT

Supported AI Models

🧪 A4 Handwritten Notes Test Data (2 pages of Scratch.pdf)

💡 Recommendation Guide

Plugin Settings

File Conflict Strategies:

• Overwrite: Replace existing file (⚠️ loses previous content)
• Skip: Don't generate if file exists
• Add Timestamp: Append timestamp to filename
• Model-based Naming (Recommended): Append model name (e.g., my_notes_qwen.md)

📊 Performance

Real Results

See actual output from different models:

• Qwen Result - Best cost-effectiveness
• OpenAI Result - Highest accuracy
• Original PDF - Input example

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License

Enjoy pdf-to-md! If you find it helpful, please consider giving it a Star ⭐ on GitHub!