Из Markdown в PDF и обратно: что сохраняет конвертация форматов
Markdown↔PDF сохраняет заголовки, списки и простые таблицы лучше пикселей. Точные шрифты, пагинация и вёрстка не выживают как цикл без потерь.
Markdown и PDF оптимизированы под разные контракты. Markdown — это структура, удобная для контроля версий. PDF — фиксированное описание страницы. Конвертировать в одну сторону и обратно полезно; это не цикл архивации без потерь.
Markdown в PDF: структура становится страницами
Markdown в PDF (POST /api/v1/convert/markdown/pdf) принимает файл .md или ZIP, содержащий Markdown. Загрузки, не являющиеся Markdown или ZIP, отклоняются. Для простого входного .md требуется UTF-8. Конвейер отрисовывает Markdown в HTML с включёнными таблицами, зачёркиванием и списками задач, оборачивает этот HTML в CSS для печати (включая стеки шрифтов для разных письменностей и RTL, когда обнаружен арабский), затем печатает в PDF через WeasyPrint.
Что обычно переживает прямой проход:
- Заголовки, абзацы, списки и простые таблицы Markdown
- Текст на разных письменностях, который может разложить путь HTML (CJK, латиница и другие письменности, покрытые CSS для печати)
- Печатаемый, годный для отправки PDF для процессов docs-as-code
А что нет:
- Шрифты темы вашего редактора как гарантированное совпадение в любом просмотрщике
- Точные экранные переносы строк из файла
.md - Интерактивные возможности Markdown, у которых нет эквивалента в PDF (живые флажки, сворачиваемые разделы, ссылки вики)
Входной ZIP нужен, чтобы упаковать Markdown с ресурсами, которые путь HTML может найти рядом с документом. Считайте это удобством упаковки, а не гарантией, что каждое относительное изображение или ссылка на CSS будет выглядеть одинаково в любом просмотрщике.
PDF в Markdown: текстовый слой на входе, Markdown на выходе
PDF в Markdown (POST /api/v1/convert/pdf/markdown) извлекает текстовое содержимое в Markdown через pdf-inspector. Ответ — text/markdown, скачиваемый как файл .md. Лучше всего конвертируются цифровые PDF с чистым текстовым слоем. Сканированные страницы без текстового слоя дают пустой или бесполезный Markdown, пока вы сначала не выполните OCR, — а OCR на этом сайте тоже возвращает Markdown, а не слой поиска в PDF.
Ожидайте:
- Заголовки и абзацы, когда эвристики по размеру шрифта срабатывают правильно (уровни
#всё равно, возможно, придётся перенумеровать вручную) - Таблицы как таблицы Markdown, когда распознавание работает; многоколоночные макеты могут выстроиться в другой порядок чтения
- Колонтитулы, повторяющиеся на каждой странице (обрезайте после)
- Изображения и формулы-картинки, которые не становятся автоматически локальными ресурсами или LaTeX
Если нужна чистая проза без эвристик заголовков, PDF в текст — более плоское извлечение. Экспорт табличного вида, возвращающий HTTP 204, означает, что колоночные блоки не обнаружены; см. Пустой экспорт таблиц (204).
Что на самом деле доказывает цикл
| Разумно переживает | Обычно нет |
|---|---|
| Слова, иерархия заголовков, структура списка | Пиксельно точная геометрия страницы |
| Простые таблицы как текст | Точные шрифты и кернинг |
| Рабочий черновик для Git или агентов | Печатная идентичность пагинации |
Двойной цикл вызовет дрейф. Markdown→PDF переразбивает через WeasyPrint; PDF→Markdown перестраивает структуру из эвристик извлечения. Ни один шаг не хранит промежуточное представление без потерь для модели вёрстки другого формата.
Выберите каноническое направление
Если печатная вёрстка нужна как система записи, храните PDF, а Markdown считайте экспортом или лентой для агентов. Если нужны диффы, код-ревью и подача агенту, предпочитайте Markdown, а PDF считайте шагом публикации. Не храните оба как равные «источники истины» и не ждите, что после правок они останутся идентичными.
Практический цикл docs-as-code: правьте Markdown в Git → Markdown в PDF для артефакта для отправки → не делайте PDF→Markdown→PDF ежедневной привычкой. Используйте PDF→Markdown, когда вы унаследовали цифровой PDF и нужен текст для агента, а затем считайте этот Markdown новым черновиком, а не гарантией исходной пагинации.
Зашифрованным файлам нужен авторизованный Unlock до любой из конвертаций. Повреждённые файлы, которые не разбираются, должны сначала пройти Get Info / Repair. О тех же эндпоинтах по HTTP см. Разработчикам.