Блоки кода Markdown в PDF: ограждения, длинные строки и разрывы страниц

Код — это то место, где документ Markdown чаще всего хорошо выглядит на экране и разваливается на бумаге. Строка, которая помещается на широком мониторе, может уйти за правое поле страницы A4. Ограждённый блок может оказаться внизу страницы так, что две строки останутся на одной стороне, а остальное — на следующей. А блок без языкового тега может отрисоваться иначе, чем соседний.

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

Это руководство охватывает ограждённые блоки, языковые теги, длину строк, темы и проверки, которые ловят проблемы до отправки PDF. Сквозной процесс описан в статье Как преобразовать README с GitHub в PDF.

Что конвертер делает с ограждением

GitHub-flavored Markdown поддерживает ограждённые блоки кода, ограниченные тремя и более обратными кавычками или тильдами. md2pdf разбирает эти ограждения, сохраняет текст точно и отрисовывает его в элементе <pre><code>. Языковой тег после открывающего ограждения сохраняется как имя класса, но текущий рендерер не применяет тему подсветки синтаксиса.

Это означает две вещи:

• Отступы, пустые строки и пунктуация сохраняются.
• Визуальный результат — моноширинный текст с фоновым цветом и рамкой кода из темы, а не цветные токены.

Если документ опирается на цвет, чтобы объяснить diff, добавьте короткую подпись или используйте в исходнике маркеры + и -. Не предполагайте, что читатель различит зелёный и красный в напечатанной копии.

Используйте ограждённые блоки, а не отступы

Отступ в четыре пробела тоже создаёт блок кода в Markdown, но ограждениями легче управлять. Они явно задают начало и конец, поддерживают языковой тег и не ломаются, когда строка внутри блока случайно оказалась с отступом.

Простой ограждённый блок:

npm install
npm run build
npm test

Используйте ограждение длиннее любой последовательности обратных кавычек внутри содержимого. Если код содержит тройные обратные кавычки, открывайте и закрывайте четырьмя. Это особенно важно для документации о самом Markdown, где ограждение может быть частью примера.

Избегайте смешивания табуляции и пробелов внутри блока. Рендерер сохраняет то, что вы написали, и несогласованные отступы выглядят как ошибка, даже когда код корректен.

Помечайте язык, даже без подсветки

Языковой тег полезен, даже когда подсветки синтаксиса нет. Он документирует предполагаемый язык, помогает редакторам и линтерам и даёт переводчикам ясный сигнал, что блок переводить нельзя. Он также упрощает поиск по исходнику.

Распространённые теги: bash, js, ts, json, yaml, python, html, css, sql и text. Используйте text для вывода, логов, деревьев каталогов и всего, что не является языком программирования. Простое ограждение без тега допустимо для короткого фрагмента, но тег лучше для всего, что читатель может скопировать.

Не помечайте блок языком только потому, что его распознаёт подсветчик. Помечайте то, чем содержимое является на самом деле. Транскрипт оболочки с приглашением и выводом — это text, а не bash, если приглашение не является частью команды.

Держите строки в пределах печатной ширины

Самая частая проблема при печати — строка кода шире страницы. В предпросмотре браузера блок может прокручиваться по горизонтали. На бумаге полосы прокрутки нет, поэтому строка обрезается или весь блок уменьшается.

Нет единого ограничения на символы, которое работает для любого шрифта и размера страницы, но практический ориентир для A4 или Letter — примерно 80–90 символов. Это близко к классической ширине терминала не случайно: так моноширинный текст остаётся удобным для чтения.

Когда строка слишком длинная, меняйте исходник, а не масштаб печати:

const message = buildMessage({ owner, repo, branch, path });

Эта строка читается. Если бы у объекта было ещё восемь свойств, разделите её на строки:

const message = buildMessage({
  owner,
  repo,
  branch,
  path,
});

Для команд оболочки используйте продолжение через обратную косую черту или переменную. Для длинных URL вынесите URL на отдельную строку или используйте ссылочную сноску. Для JSON дайте форматтеру перенести объект. Цель во всех случаях одна: ни одной строки, которая зависит от горизонтальной прокрутки.

Решите, что делать с выводом и логами

Логи и вывод команд часто шире исходного кода. Они также содержат метки времени, пути и идентификаторы, которые нельзя перенести, не изменив текст.

Варианты, которые работают при печати:

• Сократите вывод. Покажите значимые строки и добавьте многоточие в тексте, а не внутри блока кода.
• Разделите транскрипт. Поместите команду в один блок, а важный вывод — в другой, с предложением между ними.
• Используйте таблицу для структурированного вывода. Если вывод действительно состоит из строк и столбцов, таблица может напечататься лучше моноширинного блока.
• Уменьшайте шрифт только в крайнем случае. Изменения темы влияют на весь документ, а мелкий код читать труднее, чем более короткий пример.

Не вставляйте в PDF лог на 200 строк, если только лог не является документом. Читатель, которому нужен полный лог, может обратиться к репозиторию; PDF должен показывать суть.

Согласуйте оформление кода с темой

Четыре темы печати обращаются с кодом по-разному. Clean использует светлый фон кода и нейтральный шрифт. Business использует более тёмный блок кода, контрастирующий с основным текстом с засечками. Academic оставляет код светлым и второстепенным по отношению к тексту. Dark — тема, рассчитанная прежде всего на экран, чья таблица стилей для печати принудительно делает текст и фон кода светлыми.

Два практических следствия:

1. Проверяйте контраст в фактической теме. Блок кода, который хорошо выглядит в Clean, может оказаться тяжёлым в Business или слишком бледным в Academic.
2. Включайте фоновую графику при печати. Без неё фон кода исчезает и блок держится только на рамке. Текст остаётся читаемым, но визуальное разделение слабее.

Если документ состоит в основном из кода, Clean обычно самый безопасный выбор. Если это отчёт с несколькими фрагментами, подойдёт Business, но держите фрагменты короткими. Полное сравнение — в статье Clean vs Business vs Academic vs Dark.

Проверьте напечатанную страницу

Откройте сохранённый PDF и просмотрите каждый блок кода, а не только первый. Ищите:

• Обрезанные строки. Увеличьте правый край. Строка, которая заканчивается посреди токена, — признак того, что блок слишком широкий.
• Оторванные ограждения. Блок не должен начинаться одной строкой внизу страницы. Если так происходит, добавьте перед ним предложение или скорректируйте окружающий текст.
• Сломанные отступы. Табуляция и пробелы должны выглядеть согласованно. Скопированный блок со смешанными отступами — проблема исходника, а не рендерера.
• Потерянные пустые строки. Пустые строки внутри блока значимы. Убедитесь, что PDF их сохраняет.
• Нечитаемый контраст. Напечатайте страницу в оттенках серого, если документ могут копировать.
• Языковые теги в подписях. Если тег важен читателю, упомяните язык в тексте. Сам тег не отображается как метка.

Финальная проверка в другом браузере полезна, если документ будет широко распространяться. Движки печати по-разному обрабатывают разрывы страниц и фоновую графику, даже когда HTML одинаков.

Блоки кода — та часть документа Markdown, которую чаще всего копируют в другой инструмент. Держите их короткими, точными и в пределах страницы. PDF не обязан воспроизводить IDE; он должен позволить читателю понять и переиспользовать фрагмент. Подробнее о том, что остаётся локальным при преобразовании, — в статье Markdown в PDF только в браузере.