Таблица — одна из первых вещей, которые читатель ищет в технической документации. И одна из первых, что ломается, когда Markdown превращается в PDF. Столбцы, которые нормально выглядят в широком окне браузера, становятся тесными на A4, длинный текст в ячейке выталкивает сетку за поля, а строки разрываются между страницами так, что заголовок теряет смысл.
md2pdf отрисовывает таблицы GitHub-flavored Markdown и передаёт результат в таблицу стилей для печати или, при экспорте книги, в рендерер A4 PDF. Инструмент может сохранить разумную таблицу читаемой, но он не может создать пространство из ничего. Основная работа происходит в исходном Markdown: выбрать правильные столбцы, держать ячейки короткими и решить, что вообще должно быть таблицей.
Это руководство сначала разбирает работу на уровне исходника, а затем — проверки печати, которые ловят оставшиеся проблемы. Полный процесс преобразования описан в статье Как преобразовать README с GitHub в PDF.
Почему таблицы ломаются при печати
Таблица в браузере гибкая. Она может выйти за пределы контейнера, уменьшить текст или дать читателю прокрутить её вбок. У напечатанной страницы фиксированная ширина и нет полосы прокрутки. Когда содержимое шире страницы, что-то должно уступить: рендерер может обрезать таблицу, уменьшить её ниже читаемого размера или вписать в макет, который уже не похож на предпросмотр.
Три привычки усугубляют это:
- Слишком много столбцов. Восемь узких столбцов читать труднее, чем четыре широких, даже если данные технически полны.
- Абзацы внутри ячеек. Ячейка с тремя предложениями превращает таблицу, которую можно быстро просмотреть, в стену текста.
- Неограниченный код или URL. Один длинный токен может задать минимальную ширину всего столбца.
Решение — не более мелкий шрифт. Это таблица с меньшим числом задач.
Начните с таблицы, которая помещается
Полезная таблица имеет одну цель и небольшое число столбцов. Следующий пример сравнивает темы печати, не пытаясь задокументировать каждое свойство CSS:
| Setting | Clean | Business | Academic |
| --- | :--- | :--- | ---: |
| Body type | Sans | Serif | Justified serif |
| Best for | Specs | Reports | Course readers |
| Tone | Neutral | Formal | Editorial |Эта таблица свободно помещается на A4 и Letter. Она также переживает перевод, потому что ячейки короткие. Маркеры выравнивания необязательны, но упрощают просмотр исходника: :--- для выравнивания по левому краю, :---: — по центру, ---: — по правому краю для чисел.
Используйте выравнивание ради смысла, а не украшения. Числа лучше читаются по правому краю; короткие подписи — по левому. Выравнивание по центру нужно редко и может усложнить просмотр столбца.
Выбирайте столбцы по вопросу, а не по данным
Прежде чем добавить столбец, спросите, на какой вопрос отвечает таблица. Таблица миграции может отвечать на вопрос «что меняется и что мне с этим делать?». Это даёт три столбца: элемент, изменение и действие. Экспорт базы данных с двенадцатью полями — не таблица для PDF, а дамп данных.
Хорошая проверка — прочитать строку заголовков вслух. Если заголовки не образуют связного предложения или сравнения, таблица, вероятно, несёт слишком много. Разделите её или перенесите детали в текст.
Для широких справочных данных рассмотрите вместо этого список определений из двух столбцов:
| Field | Meaning |
| --- | --- |
| `owner` | GitHub user or organization |
| `repo` | Repository name without the host |
| `ref` | Branch, tag, or commit SHA |Этот формат проще печатать и переводить, чем сетку с отдельным столбцом для каждой локали или каждого крайнего случая.
Держите ячейки короткими и удобными для просмотра
Таблицы нужны для сравнения, а не для изложения. Если ячейке нужно больше двух коротких предложений, перенесите объяснение под таблицу, а в ячейке оставьте краткое изложение.
Практические правила:
- Используйте фрагменты предложений. «Требуется публичный репозиторий» — достаточно; полный абзац не нужен.
- Указывайте единицы в заголовке. Напишите
Size (MB)один раз, а не повторяйте «MB» в каждой строке. - Избегайте переносов строк внутри ячеек. GFM поддерживает
<br>, но ячейка с принудительными переносами редко хорошо разбивается на страницы. - Делайте ссылки короткими. Ссылайтесь на короткую подпись, а не на полный URL. Длинные URL становятся неразрывными токенами.
- Не полагайтесь на цвет. PDF могут печатать в чёрно-белом виде, а темы меняют палитру.
Если ячейка должна содержать длинную команду или путь, вынесите её в ограждённый блок кода под таблицей и ссылайтесь на неё по названию. Так сетка останется узкой.
Обработайте широкие данные до экспорта
Некоторые таблицы действительно широкие. Когда столбцы убрать нельзя, меняйте форму документа, а не боритесь со страницей.
Разделите по аудитории. Таблице для операторов не нужны те же столбцы, что таблице для разработчиков.
Разделите по времени. Таблица изменений с двадцатью релизами может стать отдельной таблицей для каждой мажорной версии.
Транспонируйте данные. Если атрибутов много, а элементов мало, перечислите атрибуты строками, а элементы — столбцами. Таблица станет высокой вместо широкой, а это лучше разбивается на страницы.
Перейдите к списку. Если большинство ячеек пусты или повторяются, таблица скрывает список. Текст с подзаголовками часто понятнее.
После перестройки ещё раз проверьте исходник на двух частых виновников ширины: длинный URL без разрывов и участок кода без пробелов. Оба могут сделать столбец шире страницы.
Проверьте разбивку на страницы и повтор заголовков
Таблица, которая помещается на одной странице, может не справиться, когда занимает две. Строка заголовков должна повторяться, строки не должны разрываться посреди ячейки, а таблица не должна начинаться в самом низу страницы, где видна только одна строка.
Браузерный движок печати и рендерер PDF для книги обрабатывают разбивку по-разному, поэтому проверяйте фактический результат, а не предполагайте. При печати одного документа ищите повторяющийся <thead> и избегайте разрывов страниц непосредственно перед таблицей. При экспорте книги рендерер A4 раскладывает строки последовательно; очень высокая строка всё равно может создать неудобную страницу.
Если таблица занимает несколько страниц, добавьте над ней короткую подпись, где названы столбцы. Подпись даёт читателю контекст, когда заголовок остался на предыдущей странице. Держите подпись обычным текстом, а не внутри таблицы.
Контрольный список перед экспортом
Прежде чем печатать или экспортировать, пройдитесь по списку:
- У таблицы одна цель и не больше пяти-шести столбцов.
- Каждый заголовок короткий и, где нужно, содержит единицу измерения.
- В ячейках фрагменты, а не абзацы.
- Ни одна ячейка не содержит полный URL или неразрывный токен длиннее страницы.
- Выравнивание применено к числам и коротким подписям, а не везде.
- У таблицы есть подпись, если она занимает больше одной страницы.
- Вы проверили фактический PDF, а не только предпросмотр в браузере.
О поведении конкретных тем читайте в статье Clean vs Business vs Academic vs Dark. Тема с засечками и более узкими полями может потребовать на один столбец меньше, чем тема Clean по умолчанию.
Таблицы не обязаны быть красивыми. Они должны оставаться читаемыми, когда покидают браузер. Более узкая и короткая таблица с понятной подписью почти всегда лучше полной сетки, для понимания которой читателю нужно увеличивать масштаб.
Создайте свой PDF из README
Бесплатно, без регистрации и полностью в браузере.