Конвертировать Markdown в PDF

Какой Markdown и во что он превращается

Markdown — это семейство, а не единая спецификация. Общее ядро — заголовки, выделение, списки, ссылки, изображения, цитаты, блоки кода — везде одинаково, а дальше каждая реализация отличается. Здесь поддерживается широко принятый расширенный набор: таблицы, блоки кода с подсветкой синтаксиса, списки задач, зачёркивание, сноски и front matter. Это покрывает то, что пишут почти все, и границу лучше знать заранее, чем обнаружить.

Заголовки становятся настоящей структурой PDF, а не просто крупным текстом: у них есть уровни, поэтому в PDF появляется боковая панель закладок для навигации. Ссылки становятся работающими аннотациями-ссылками. Блоки кода набираются моноширинным шрифтом с подсветкой — в этом разница между документом, который приятно читать, и серой стеной текста. Размер страницы и поля подобраны для чтения, а не унаследованы, ведь у файла Markdown нет мнения о бумаге.

Изображения должны быть доступны, и это самое частое разочарование. Файл Markdown ссылается на картинки, а не содержит их, поэтому относительный путь работает, только если изображение перетащено вместе с файлом, а веб-адрес — только если сервер разрешает другим сайтам его загружать. Изображение, которое не удалось найти, помечается в PDF подписью, а не оставляет молчаливый пропуск, так что недостающую схему вы увидите сразу, а не после отправки документа.

Две вещи намеренно показываются как код, а не отрисовываются. Математическим формулам в нотации LaTeX и диаграммам Mermaid нужен собственный рендерер, а неправильная отрисовка хуже исходника: неверно отрисованное уравнение ошибочно так, что этого никто не заметит. Сырой HTML внутри Markdown обрабатывается для простого строчного оформления, но не для вёрстки, потому что произвольному блоку разметки не место в документе, разбитом на страницы.

Если нужно другое

Pandoc — серьёзный инструмент для этой задачи, и он бесплатен. pandoc doc.md -o doc.pdf --pdf-engine=xelatex верстает через LaTeX, что даёт по-настоящему красивый результат с правильными переносами, контролем висячих строк и настоящим оглавлением, а с шаблоном вы управляете каждым аспектом дизайна. Он также правильно отрисовывает математику LaTeX — как раз то, чего здесь нет. Цена — установка дистрибутива TeX, а он немаленький.

Для документации, а не разового документа, генератор статических сайтов или mdBook дают нечто лучшее, чем PDF: с поиском, ссылками и удобным чтением на телефоне. Конвертируйте в PDF, когда документ нужно распечатать, приложить или отправить в архив, — и в любом случае храните Markdown как первоисточник, ведь именно эту версию можно редактировать и сравнивать.