PDF to Markdown Note Extractor

I take notes using pen and paper (usually a fountain pen, such as the Mahjohn A1 vanishing point clone) and some lined paper (currently letter-side notebook paper, made in Vietnam from Daiso) because I tend to remember it better than if I'm taking notes directly on the computer. I have an Epson DS-510 for sheetfed scanning, so I can very quickly go from the loose-leaf paper into a nice PDF suitable for processing.

My notes typically have a few conventions:

• I will start a note with a date and a sequence letter. This is usually something like 2026-02-27A.
• The next line may be the title or the start of the note.
• The last line of the note may be END

For example:

2026-02-27A Sample Note

• I have some notes here
• Maybe a few lines
  • Maybe an indent END

I'd prefer not to ship off that data to a third party, especially since there are good enough vision models these days to just run locally on my mac using LM Studio. I'm currently using the qwen3-vl-8b model, but there's probably better ones for this use case.

I'd initially tried to go directly from the PDF into chunked files, but there's plenty to correct, so instead I'm doing this as two passes, one where it goes into one large markdown file and I hand-fix any issues using the PDF as reference, and then once that's in a good state, I then chunk it out into individual files. Not everything has a title, so I also use LM Studio to generate one when there doesn't exist one.

Features

• Convert PDF pages to images
• Send images to LM Studio for OCR
• Extract notes with dates and optional sequence letters
• Handle multi-page notes
• Create separate markdown files for each note
• Automatic note type inference
• Support for notes without date patterns

Installation

1. Create a virtual environment:

python -m venv venv

2. Activate the virtual environment:

• macOS/Linux:

source venv/bin/activate

• Windows:

venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Configuration

The script uses the following configuration from config.py:

• LM_STUDIO_URL: API endpoint for LM Studio (default: http://localhost:1234/v1/chat/completions)
• IMAGE_DPI: DPI for PDF to image conversion (default: 300)
• OUTPUT_DIR: Output directory for markdown files (default: notes)
• DEFAULT_MODEL: Default LM Studio model (default: qwen/qwen3-vl-8b)

You can override these settings via command-line arguments or by creating a .env file.

Usage

Basic Usage

python main.py --pdf input.pdf

This will:

• Convert the PDF to images (300 DPI)
• Send each image to LM Studio for OCR
• Extract notes with dates and sequence letters
• Save markdown files to the notes directory

Custom Output Directory

python main.py --pdf input.pdf --output my_notes

Custom Model

python main.py --pdf input.pdf --model qwen/qwen3-vl-8b

Custom DPI

python main.py --pdf input.pdf --dpi 200

All Options

python main.py --pdf input.pdf --output notes --model qwen/qwen3-vl-8b --dpi 300

File Naming Convention

Markdown files are named using the format:

{date}{sequence}-{description}.md

Examples:

• 2024-02-08A-meeting-notes.md - Note from 2024-02-08 with sequence A
• 2024-02-08B-project-planning.md - Note from 2024-02-08 with sequence B
• 2024-02-08-untitled.md - Note from 2024-02-08 without sequence
• 2026-02-26-meeting-notes.md - Note without date pattern

Description Generation

The description is generated from:

1. The first line of the note (sanitized and truncated)
2. If the first line doesn't seem related to the note content, LM Studio generates a 2-3 word summary

Note Type Inference

The script automatically detects note types:

Notes with Date Pattern

If a line matches the pattern YYYY-MM-DD (e.g., 2024-02-08), it's treated as a note start. The date is extracted and used in the filename.

Notes Without Date Pattern

If no date pattern is found, the current date (or the date of the last note) is used in the filename.

Multi-page Notes

Notes can span multiple pages. The script tracks the current note and continues appending content until a new date pattern is detected.

Output Format

Each markdown file contains:

# {title}

**Date:** {date}

**Sequence:** {sequence}

{content}

Requirements

• Python 3.8+
• LM Studio running locally
• PDF file with handwritten notes

Dependencies

• pdf2image - Convert PDF to images
• pillow - Image processing
• requests - HTTP requests to LM Studio
• pydantic - Data validation
• python-dotenv - Environment variables

Troubleshooting

LM Studio Connection Failed

Ensure LM Studio is running locally at http://localhost:1234. You can start LM Studio with:

lm-server

PDF Conversion Failed

Make sure you have Ghostscript installed (required by pdf2image):

• macOS: brew install ghostscript
• Linux: sudo apt-get install ghostscript
• Windows: Download from Ghostscript website

Poor OCR Quality

• Try increasing the DPI: --dpi 400
• Ensure handwritten notes are clear and well-lit
• Use a higher quality vision model

Examples

Example 1: Simple Note

Input PDF with one handwritten note:

2024-02-08
Meeting notes
- Discuss project timeline
- Review budget
- Schedule next meeting

Output file: 2024-02-08-meeting-notes.md

Example 2: Multiple Notes

Input PDF with multiple notes:

2024-02-08A
Project kickoff meeting
- Define project scope
- Assign team members

2024-02-08B
Budget review
- Review expenses
- Approve new budget

Output files:

• 2024-02-08A-project-kickoff-meeting.md
• 2024-02-08B-budget-review.md

Example 3: Multi-page Note

Input PDF with a note spanning two pages:

2024-02-10
Research notes
Page 1:
- Study competitor analysis
- Review market trends

Page 2:
- Identify key differentiators
- Develop positioning strategy

Output file: 2024-02-10-research-notes.md

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.