PDF to Markdown Converter

Мощный CLI-инструмент для конвертации PDF-файлов в Markdown формат с автоматическим определением наличия текстового слоя и применением OCR при необходимости.

🎯 Особенности

• ✅ Автоматическое определение типа PDF - распознаёт, нужен ли OCR или можно извлечь текст напрямую
• ✅ Поддержка OCR - использует Tesseract с поддержкой русского и английского языков
• ✅ Оптимизирован для технической документации - идеален для книг по программированию, архитектуре ПО, API документации
• ✅ Пакетная обработка - конвертирует все PDF из папки за один запуск
• ✅ Подробное логирование - отслеживание каждого этапа конвертации
• ✅ Обработка ошибок - продолжает работу даже если один файл не удалось обработать
• ✅ Метаданные в выходных файлах - каждый .md файл содержит информацию об источнике и методе конвертации

📋 Требования

Система

• Python 3.7 или выше
• Tesseract OCR (для обработки отсканированных документов)

Python библиотеки

• extractous - библиотека для извлечения текста из PDF
• PyPDF2 - для проверки наличия текстового слоя

🚀 Установка

1. Установка Tesseract OCR

Ubuntu/Debian

sudo apt-get update
sudo apt-get install tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng

macOS

brew install tesseract tesseract-lang

Windows

Скачайте установщик с GitHub и установите.

После установки добавьте путь к Tesseract в переменную PATH.

2. Установка Python зависимостей

# Создайте виртуальное окружение (рекомендуется)
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# или
venv\Scripts\activate  # Windows

# Установите зависимости
pip install extractous PyPDF2

3. Скачивание скрипта

Сохраните pdf_to_md_converter.py в рабочую директорию и сделайте его исполняемым:

chmod +x pdf_to_md_converter.py

📖 Использование

Базовый синтаксис

python pdf_to_md_converter.py <входная_папка> <выходная_папка>

Примеры

Простая конвертация

python pdf_to_md_converter.py ./pdf_files ./markdown_output

С подробным логированием

python pdf_to_md_converter.py ./pdfs ./output --verbose

Использование абсолютных путей

python pdf_to_md_converter.py /home/user/Documents/PDFs /home/user/Documents/Markdown

Опции командной строки

| Опция | Описание | |-------|----------| | input_dir | Путь к папке с PDF файлами (обязательный) | | output_dir | Путь к папке для сохранения Markdown файлов (обязательный) | | -v, --verbose | Включить подробное логирование (DEBUG уровень) | | --version | Показать версию программы | | -h, --help | Показать справку |

🔧 Как это работает

Алгоритм работы

1. Сканирование входной папки

   • Поиск всех файлов с расширением .pdf и .PDF
   • Формирование списка для обработки

2. Для каждого PDF файла:

   a) Определение типа документа

   • Анализ первых 3 страниц с помощью PyPDF2
   • Извлечение текста и подсчёт символов
   • Если найдено >50 символов → есть текстовый слой
   • Если <50 символов → нужен OCR

   b) Выбор метода извлечения

   • С текстовым слоем: Extractor() - быстрое извлечение
   • Без текстового слоя: Extractor().set_ocr_config(TesseractOcrConfig().set_language("rus+eng")) - OCR

   c) Конвертация

   • Извлечение содержимого через extractous
   • Форматирование в Markdown
   • Добавление метаданных

   d) Сохранение

   • Создание .md файла с тем же именем
   • Добавление заголовка и метаинформации

3. Итоговая статистика

   • Подсчёт успешных конвертаций
   • Список ошибок (если есть)
   • Общее время выполнения

Структура выходного Markdown файла

# Название_документа

*Конвертировано из: original_file.pdf*
*Метод: OCR (rus+eng)*

---

[Здесь начинается извлечённый контент]

📊 Коды возврата

Программа возвращает следующие коды завершения:

| Код | Значение | |-----|----------| | 0 | Успешная конвертация всех файлов | | 1 | Произошли ошибки при конвертации некоторых файлов | | 2 | Не найдено PDF файлов в входной папке | | 3 | Ошибка валидации входных параметров | | 130 | Операция прервана пользователем (Ctrl+C) |

📝 Пример вывода

2025-10-02 13:28:30 - INFO - Выходная папка подготовлена: ./output
2025-10-02 13:28:30 - INFO - Найдено PDF файлов: 5

============================================================
Начало конвертации 5 файлов
============================================================

2025-10-02 13:28:30 - INFO - [1/5] Обработка document1.pdf
2025-10-02 13:28:31 - INFO -   → Извлечение текста из слоя для document1.pdf
2025-10-02 13:28:35 - INFO -   ✓ Успешно сохранено: document1.md

2025-10-02 13:28:35 - INFO - [2/5] Обработка scanned_doc.pdf
2025-10-02 13:28:36 - INFO -   → Используется OCR для scanned_doc.pdf
2025-10-02 13:29:45 - INFO -   ✓ Успешно сохранено: scanned_doc.md

...

============================================================
ИТОГИ КОНВЕРТАЦИИ
============================================================
Всего файлов:       5
Успешно:            5
Ошибок:             0
============================================================

⚠️ Частые проблемы и решения

Проблема: Неполная конвертация больших документов (лимит Apache Tika)

Симптомы:

• В логах появляется: ✗ КРИТИЧНО: Достигнут лимит записи Apache Tika!
• Обрабатывается только ~250-270 страниц из больших документов
• В метаданных: 'X-TIKA:EXCEPTION:write_limit_reached': ['true']

Причина:

Extractous использует Apache Tika, которая имеет встроенный лимит ~100MB извлечённого текста. Это защита от переполнения памяти. При достижении лимита обработка прерывается.

РЕШЕНИЕ 1: Использовать альтернативный скрипт (РЕКОМЕНДУЕТСЯ)

Я создал дополнительный скрипт large_pdf_converter.py для обработки больших документов:

# Установите pypdf
pip install pypdf

# Запустите альтернативный конвертер
python large_pdf_converter.py ./input ./output

Преимущества:

• ✅ Обрабатывает все страницы без ограничений
• ✅ Постраничная обработка - не упирается в лимиты памяти
• ✅ Работает с документами любого размера
• ✅ Показывает прогресс обработки

Недостатки:

• ❌ Не поддерживает OCR (только PDF с текстовым слоем)
• ❌ Может быть медленнее для очень больших файлов

РЕШЕНИЕ 2: Marker-PDF (для максимального качества)

Marker-PDF - специализированный инструмент для конвертации книг и документации (нужен gpu 3060+ 8gb+ https://github.com/datalab-to/marker , медленно но супер-качественно):

# Установка
pip install marker-pdf

# Использование
marker-single "ваш_большой_файл.pdf" --output_dir ./output/

Преимущества:

• ✅ Оптимизирован для технических книг
• ✅ Лучшее сохранение форматирования
• ✅ Поддержка математических формул
• ✅ Обработка таблиц и кода

Альтернатива https://github.com/Unstructured-IO/unstructured

РЕШЕНИЕ 3: Разбивка на части

Разделите большой PDF на несколько частей:

Некоторые PDF имеют ограничения на извлечение текста.

Решение:

• Проверьте права доступа к PDF: pdfinfo файл.pdf
• Снимите защиту (если имеете права): qpdf --decrypt input.pdf output.pdf
• Используйте OCR режим (он может обойти некоторые ограничения)

1. Повреждённая структура PDF

   Файл может быть частично повреждён или иметь нестандартную структуру.

   Решение:

   • Попробуйте восстановить PDF:

     # С помощью Ghostscript
     gs -o repaired.pdf -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress input.pdf
     

   • Конвертируйте через промежуточный формат:

     # PDF → изображения → PDF с OCR
     pdftoppm input.pdf output -png
     img2pdf output-*.png -o new.pdf
     

2. Таймауты при обработке больших файлов

   Для очень больших документов библиотека может прерывать обработку.

   Решение: Добавьте настройку таймаута в код (требуется модификация):

   # В методе create_extractor
   extractor = Extractor()
   # Если extractous поддерживает настройку таймаута
   # extractor.set_timeout(600)  # 10 минут
   

3. Проблемы с кодировкой или специальными символами

   Некоторые страницы могут содержать символы, вызывающие ошибки парсинга.

   Решение:

   • Используйте OCR режим
   • Проверьте логи на наличие предупреждений о кодировке

Рекомендуемый workflow для больших документов:

# 1. Сначала попробуйте стандартную конвертацию
python pdf_to_md_converter.py ./input ./output --verbose

# 2. Если видите предупреждения о неполной обработке, проверьте PDF
pdfinfo "ваш_файл.pdf"

# 3. Попробуйте восстановить PDF
gs -o repaired.pdf -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress "ваш_файл.pdf"

# 4. Конвертируйте восстановленный файл
python pdf_to_md_converter.py ./input ./output --verbose

# 5. Если всё равно не работает, используйте альтернативный инструмент
marker "ваш_файл.pdf" ./output/

Проблема: "Tesseract not found"

Решение: Убедитесь, что Tesseract установлен и доступен в PATH:

tesseract --version

Если команда не работает, установите Tesseract или добавьте его в PATH.

Проблема: Медленная обработка больших файлов

Причина: OCR - это ресурсоёмкая операция.

Решение:

• Используйте PDF с текстовым слоем, если возможно
• Обрабатывайте файлы небольшими партиями
• Увеличьте количество CPU ядер для Tesseract (требуется модификация кода)

Проблема: Неправильное распознавание текста

Решение:

• Убедитесь, что установлены языковые пакеты для Tesseract (tesseract-ocr-rus, tesseract-ocr-eng)
• Проверьте качество исходного PDF (разрешение, четкость)
• Для документов только на английском языке можно изменить настройку на .set_language("eng")

Проблема: "Permission denied" при создании выходной папки

Решение: Убедитесь, что у вас есть права на запись в указанную директорию:

mkdir -p /path/to/output
chmod 755 /path/to/output