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

🔧 Настройка и кастомизация

Изменение языков OCR

Для изменения языков OCR, отредактируйте строку в методе create_extractor:

TesseractOcrConfig().set_language("rus+eng")  # Текущая настройка
TesseractOcrConfig().set_language("eng")      # Только английский
TesseractOcrConfig().set_language("rus")      # Только русский
TesseractOcrConfig().set_language("fra+eng")  # Французский + английский

Изменение порога определения текстового слоя

По умолчанию используется порог в 50 символов. Для изменения, отредактируйте строку в методе has_text_layer:

has_text = len(cleaned_text) > 50  # Текущий порог
has_text = len(cleaned_text) > 100  # Более строгий порог

Обработка вложенных папок

Для рекурсивной обработки вложенных папок, замените в методе get_pdf_files:

# Было:
pdf_files = list(self.input_dir.glob("*.pdf"))

# Станет:
pdf_files = list(self.input_dir.rglob("*.pdf"))  # rglob вместо glob

📚 Примеры использования в скриптах

Bash скрипт для массовой конвертации

#!/bin/bash

# Конвертация нескольких папок
for dir in project1 project2 project3; do
    echo "Обработка $dir..."
    python pdf_to_md_converter.py "./source/$dir" "./output/$dir"
done

echo "Все папки обработаны!"

Python скрипт с импортом класса

from pdf_to_md_converter import PDFToMarkdownConverter

# Создание конвертера
converter = PDFToMarkdownConverter(
    input_dir="./pdfs",
    output_dir="./markdown"
)

# Запуск конвертации
stats = converter.convert_all()

# Вывод статистики
converter.print_summary(stats)

# Анализ результатов
if stats['failed'] > 0:
    print(f"Внимание! {stats['failed']} файлов не удалось обработать")

🤝 Вклад в проект

Если вы нашли баг или хотите предложить улучшение:

1. Опишите проблему или предложение
2. Приложите примеры файлов (если возможно)
3. Укажите версию Python и операционную систему

📄 Лицензия

Этот проект распространяется свободно для личного и коммерческого использования.

🙏 Благодарности

• extractous - библиотека для извлечения текста
• Tesseract OCR - движок распознавания текста
• PyPDF2 - работа с PDF файлами

📞 Поддержка

При возникновении проблем:

1. Проверьте раздел "Частые проблемы и решения"
2. Запустите с опцией --verbose для подробного логирования
3. Проверьте, что все зависимости установлены корректно

---

Версия: 1.0.0
Дата обновления: 2 октября 2025