M1ck4/pdfmd

This project addresses the challenge of converting PDF documents, including scanned ones, into clean, structured Markdown. It targets researchers, professionals, and creators who require accurate, fast, and privacy-preserving document processing, offering significant benefits for workflows integrated with Obsidian and other Markdown-based note-taking systems. The tool operates fully offline, ensuring data confidentiality.

How It Works

pdfmd employs a modular, multi-stage pipeline: PDF Input → Extraction (native PyMuPDF or OCR via Tesseract/OCRmyPDF) → Transformation (text cleanup, structure detection, header/footer removal) → Table & Equation Processing → Rendering (Markdown generation) → Export. Its core advantage lies in intelligent heuristics for detecting document structure, such as headings based on font metrics, automatic table reconstruction from disparate blocks, and conversion of Unicode math to LaTeX. The privacy-first design ensures all processing occurs locally, with no data uploaded or tracked.

Quick Start & Requirements

• Primary Install: Recommended installation via pip: pip install -e .[full] for full OCR support.
• Prerequisites: Python, Tesseract OCR, and OCRmyPDF are required for OCR functionality. Platform-specific installation instructions are provided for Windows, macOS, and Linux.
• Links: Repository: https://github.com/M1ck4/pdfmd, Releases: https://github.com/M1ck4/pdfmd/releases.

Highlighted Details

• Privacy & Security: Fully offline operation, no uploads, no telemetry, no cloud processing. Secure handling of password-protected PDFs with in-memory processing.
• Intelligent Parsing: Automatic detection and removal of repeating headers/footers, smart paragraph reconstruction, orphan fragment merging, multi-column awareness, and heading inference.
• Advanced Content Recognition: Robust table detection and reconstruction into Markdown pipe tables; math-aware extraction converting Unicode math to LaTeX and preserving existing LaTeX.
• Scanned Document Support: Integrated Tesseract OCR and OCRmyPDF with auto-detection heuristics and support for 17+ languages, combinable for multi-language documents.
• User Experience: A modern GUI with dark/light themes, live preview, persistent settings, batch conversion, and user-defined profiles. Command-line interface for automation.

Maintenance & Community

The project is hosted on GitHub, serving as the primary hub for development and community interaction. Specific details regarding active maintainers, sponsorships, or dedicated community channels (like Discord/Slack) are not explicitly detailed in the README.

Licensing & Compatibility

The project is released under the MIT License, permitting free use for both personal and commercial purposes without significant restrictions.

Limitations & Caveats

OCR output quality is contingent on the original scan's clarity and the correct selection of OCR language packs. Users must install Tesseract OCR and OCRmyPDF separately for OCR features. Older versions (pre-v1.6.0) may exhibit GUI startup issues related to theme application or corrupted configuration files. Password handling is secure but requires correct input for encrypted documents.