З 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, придатний для друку й поширення, для процесів «документація як код».
Що ні:
- шрифти теми вашого редактора як гарантований збіг у кожному переглядачі;
- точні екранні розриви рядків із файлу
.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 сприймайте як крок публікації. Не зберігайте обидва як рівноцінні «джерела істини» й не чекайте, що після правок вони лишаться ідентичними.
Практичний цикл «документація як код»: редагуйте Markdown у Git → Markdown у PDF для артефакту, яким можна поділитися → уникайте PDF→Markdown→PDF як щоденної звички. Використовуйте PDF→Markdown, коли вам у спадок дістався цифровий PDF і потрібен текст для агента; тоді сприймайте той Markdown як нову чернетку, а не як гарантію початкової пагінації.
Зашифровані файли потребують дозволеного розблокування перед будь-якою з конвертацій. Пошкоджені файли, які не розбираються, мають спершу пройти через Отримати інформацію / Відновлення. Про ті самі кінцеві точки через HTTP див. Розробникам.