Markdown в PDF

Что здесь означает «Markdown в PDF»

Markdown — это формат, в котором большинство разработчиков и технических писателей на самом деле пишут: файлы README, черновики блогов, runbook'и, документация API, внутренние вики. Он лёгкий, версионируемый и чисто рендерится в GitHub. Но когда приходит время поделиться этим документом с тем, кто не работает в вашем репозитории, PDF обычно является правильным форматом для передачи: он печатается предсказуемо, открывается на любом устройстве и не зависит от того, установлен ли у получателя просмотрщик markdown.

Инструмент Markdown в PDF от imisspdf берёт исходный markdown, который вы вставляете (или перетаскиваете как файл .md), и создаёт один PDF в вашем браузере. Заголовки сохраняют свою иерархию, списки сохраняют отступы, блоки кода в ограждении отрисовываются моноширинным шрифтом, а цитаты / горизонтальные линии выглядят как цитаты и линии. Результат — чистый PDF без излишеств, подходящий для README, технического отчёта или журнала изменений, переданного нетехническому читателю.

Как работает конвертация

Три этапа выполняются от начала до конца в вашей вкладке:

1. Парсер marked преобразует ваш markdown в HTML с включёнными правилами GFM (код в ограждении, зачёркивание, списки задач, автоссылки).
2. Небольшой токенизатор на основе регулярных выражений проходит по HTML и превращает его в плоскую последовательность блочных токенов — заголовки, абзацы, списки, блоки кода, цитаты — и их строчные фрагменты (жирный, курсив, строчный код, ссылки).
3. pdf-lib раскладывает блоки по страницам, используя 14 стандартных шрифтов PDF (Helvetica для основного текста, Courier для кода). Новые страницы добавляются по мере переполнения содержимым.

Ничто в этом процессе не общается с сервером. Нет удалённо отрендеренного markdown, нет безголового Chromium, запускающегося в облачной функции, нет временного файла, удерживаемого «час ради соблюдения хранения». PDF собирается из байтов JavaScript, которые вы можете видеть в своих DevTools.

Когда инструмент подходит — а когда нет

Этот инструмент подходит, когда вам нужен чистый, архивируемый PDF технического содержания: README, runbook, отчёт, написанный в markdown, заметки со встречи, руководство. Он обрабатывает строчное форматирование, списки, код и цитаты так, как вы бы ожидали для документа такого типа.

Это неподходящий инструмент, когда вам нужна пиксельная точность с отрендеренным сайтом (используйте опцию «Сохранить как PDF» в вашем браузере на отрендеренной странице), когда вам нужны типографские таблицы (используйте Pandoc + LaTeX локально) или когда вам нужен код с подсветкой синтаксиса (экспортируйте из вашего редактора как HTML и используйте HTML в PDF). Мы называем ограничения заранее, чтобы вы выбрали правильный рабочий процесс.

Приватность и безопасность

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

Советы для хорошего результата

• Используйте настоящие заголовки. Символ # в начале строки становится h1; более низкие уровни вкладываются чисто. Просмотрщики PDF и программы чтения с экрана подхватывают структуру.
• Сохраняйте блоки кода в ограждении. Блоки с тройными обратными кавычками отрисовываются в Courier, поэтому отступы читаются правильно даже при переносе.
• Избегайте markdown с большим количеством изображений. Внешние изображения не загружаются. Преобразуйте изображения в PDF отдельно и объедините их.
• Для таблиц сначала отрендерьте markdown в вашем инструменте, а затем сделайте скриншот. Или используйте Pandoc локально для типографских таблиц.

Похожие инструменты PDF

• HTML в PDF — тот же рендерер, с вводом HTML вместо markdown.
• TXT в PDF — простой текст без какого-либо форматирования.
• Объединить PDF — объединяет PDF из markdown с изображениями или другими файлами.
• Сжать PDF — уменьшает результат для передачи.