Выбор темы в md2pdf выглядит как мелочь: четыре переключателя над кнопкой экспорта. На практике он меняет то, как документ читается ещё до того, как кто-то доберётся до содержания. Спецификация, напечатанная в Academic, выглядит как научная работа. Клиентское предложение, напечатанное в Clean, выглядит как выгрузка репозитория. Правильная тема — та, что соответствует ожиданиям читателя.
Все четыре темы отрисовывают один и тот же Markdown. Они различаются семейством шрифтов, выравниванием, оформлением кода, стилем таблиц, цветом ссылок и тем, сколько визуальной структуры добавляют заголовкам. Ни одна из них не добавляет водяной знак, обложку или логотип. Содержание остаётся вашим.
Темы — это таблицы стилей печати, а не смена цветов
Каждая тема — набор правил CSS, применяемых к листу предпросмотра и переносимых в вывод на печать. Это значит, что тема влияет на:
- Шрифт заголовков, основного текста, таблиц и кода.
- Выравнивание основного текста: по левому краю или по ширине.
- Цвет и толщину линеек под заголовками.
- Фон блоков кода и встроенного кода.
- Заливку заголовков таблиц и цвета границ.
- Цвет ссылок в предпросмотре и, если PDF его сохраняет, в экспортированном файле.
Таблица стилей печати также управляет подсказками для разбивки на страницы: блоки кода, таблицы, цитаты и изображения по возможности избегают разрыва посередине, а заголовки не остаются в одиночестве внизу страницы.
Одно практическое замечание перед сравнением: включите Background graphics (Фоновую графику) в диалоге печати браузера, если хотите сохранить заливку блоков кода и цвета заголовков таблиц. Без этого PDF остаётся читаемым, но темы Business и Dark теряют часть структуры. Выбор делается в диалоге печати, а не в приложении.
Clean: вариант по умолчанию для технических документов
Clean — нейтральный вариант. Он использует тот же стек шрифтов без засечек, что и интерфейс, для всего документа: тёмно-серый текст на белом и светло-серый фон кода. Заголовки разделены тонкой линейкой, а ссылки используют тот же сине-зелёный цвет, что и в остальном продукте.
Для чего лучше всего подходит:
- README репозиториев и технические спецификации.
- Внутренняя инженерная документация.
- Раздаточные материалы и ранбуки с большим количеством кода.
- Документы, которые будут читать на экране так же часто, как на бумаге.
- Снимки для аудита, где нейтральность важнее лоска.
На что обратить внимание:
- Очень длинный текст может казаться плоским. Clean эффективен, но не уютен.
- Светлый фон кода зависит от фоновой графики при печати. Если её отключить, блоки кода всё ещё читаются, но теряют визуальное отделение от основного текста.
- Основной текст без засечек при мелком кегле может быть менее удобным для долгого чтения, чем шрифт с засечками.
Clean — самый безопасный вариант по умолчанию, потому что он не навязывает тон. Если вы экспортируете README для другого инженера, начните с него.
Business: отчёты, предложения и передача клиентам
Business переводит документ в более официальный тон. Он использует шрифт с засечками по всему документу, тёмно-синие заголовки с более тяжёлой линейкой, тёмный блок кода и тонированный заголовок таблицы. Результат больше похож на отчёт, чем на README, — и в этом весь смысл, когда аудитория — клиент, руководитель или представитель смежной команды.
Для чего лучше всего подходит:
- Передача проектов клиентам и обзоры проектов.
- Предложения, описания объёма работ и отчёты.
- Раздаточные материалы мастер-классов, которые должны выглядеть оформленными.
- Приложения к портфолио и образцы заявок.
- Документы, где схемы и таблицы несут не меньший вес, чем текст.
На что обратить внимание:
- Тёмный блок кода — сильный визуальный элемент. Документ с множеством коротких фрагментов кода может начать выглядеть полосатым.
- Шрифт с засечками и почти выровненный по ширине текст делают длинные URL и идентификаторы кода заметными. Держите строки кода короткими.
- Здесь важна фоновая графика. Без неё тёмный блок кода становится простым блоком, а заголовок таблицы теряет тонировку.
- Business не заменяет редактирование. Сырой список изменений в Business всё равно читается как сырой список изменений.
Для внешних документов Business обычно производит лучшее первое впечатление. Он сигнализирует, что PDF подготовили для читателя, а не выгрузили в спешке.
Academic: длинные тексты и учебные материалы
Academic использует шрифт с засечками, выровненный по ширине основной текст и более тёплое, светлое оформление кода. Заголовки остаются выровненными по левому краю, чтобы структура оставалась просматриваемой, даже когда абзацы выровнены по ширине. Общий эффект ближе к учебному сборнику или научной работе, чем к странице продукта.
Для чего лучше всего подходит:
- Учебные комплекты, сборники для чтения и конспекты лекций.
- Научные работы и исследовательские отчёты.
- Длинная документация с небольшим количеством блоков кода.
- Заявки на гранты и академические портфолио.
- Любой документ, который читатель собирается читать подряд, а не просматривать.
На что обратить внимание:
- Выравнивание по ширине может создавать широкие пробелы вокруг длинных URL, идентификаторов кода и технических терминов. Превращайте длинные ссылки в ссылки-сноски или выносите их в список.
- Блоки кода читаемы, но визуально тише, чем в Business. Это намеренно: Academic предполагает, что код — вспомогательный материал, а не главное событие.
- Таблицы могут становиться тесными на A4, если в них много столбцов. Уменьшите число столбцов или перенесите детали в текст.
- Academic плохо подходит для краткого руководства по настройке. Формат говорит «читайте от начала до конца», а ранбук обычно просматривают.
Если в документе есть раздел вроде библиографии, типографика Academic делает его уместным. Приложение не форматирует цитаты, поэтому оставьте раздел с источниками в Markdown.
Dark: сначала экран, вывод безопасен для печати
Dark стоит особняком. Он создан в первую очередь для комфортного чтения на экране: тёмно-синий фон, светлый текст и более яркий цвет ссылок. При печати таблица стилей принудительно задаёт белый фон, чёрный текст, чёрные ссылки и светлые блоки кода. PDF не переносит тёмную экранную тему на бумагу.
Для чего лучше всего подходит:
- Просмотр длинного README на экране перед экспортом.
- Вечернее чтение или чтение при слабом свете.
- Проверка того, как документ читается без визуального шума белой страницы.
- Создание PDF в команде, которая предпочитает инструменты с тёмной темой.
На что обратить внимание:
- То, что вы видите на экране, не совпадает с тем, что получится в PDF. Всегда открывайте экспортированный файл, чтобы убедиться в светлом оформлении для печати.
- Dark — не фирменная тема для внешних документов. Клиент ожидает, что PDF будет соответствовать печатному выводу, а не предпросмотру.
- Если в браузере включена печать фонов, таблица стилей всё равно переопределяет тёмные поверхности, но блоки кода могут потребовать визуальной проверки.
- Экранный контраст темы может скрывать слабую структуру исходника. Документ с пропущенными заголовками всё равно выглядит стильно; лучше организованным он не становится.
Воспринимайте Dark как режим чтения с безопасным для печати выходом, а не как четвёртую визуальную идентичность итогового документа.
Сравнение в одной таблице
| Clean | Business | Academic | Dark | |
|---|---|---|---|---|
| Основной шрифт | Без засечек | С засечками | С засечками, по ширине | Без засечек на экране; светлый при печати |
| Оформление заголовков | Тонкая линейка | Тёмно-синяя линейка | Шрифт с засечками, по левому краю | Светлая линейка на тёмном; безопасно для печати |
| Блоки кода | Светло-серые | Тёмно-синие | Тёплые светлые | Тёмные на экране; светлые при печати |
| Заголовки таблиц | Нейтральные | Тонированные синим | Нейтральные | Тёмные на экране; светлые при печати |
| Цвет ссылок | Сине-зелёный | Синий | Чёрный | Ярко-синий на экране; чёрный при печати |
| Лучшая аудитория | Инженеры | Клиенты, руководители | Исследователи, студенты | Автор, на экране |
| Лучший документ | Спецификация, README, ранбук | Отчёт, предложение, раздаточный материал | Научная работа, учебный комплект | Копия для проверки |
Таблица — отправная точка, а не правило. Технический клиент может предпочесть Clean. Команда инженеров с вниманием к дизайну может предпочесть Business. Задача документа важнее его категории.
Как тема взаимодействует с остальным экспортом
Тема — лишь часть результата печати. Эти взаимодействия стоит проверить:
Оглавление. Оглавление наследует шрифт документа и цвет ссылок. В Business тёмно-синие заголовки и синие ссылки делают его похожим на страницу содержания отчёта. В Academic оно читается как план научной работы. Оглавление создаётся для документов с тремя и более заголовками, и его можно отключить, если документ короткий.
Блоки кода. Clean и Academic используют светлый фон кода; Business — тёмный блок; Dark использует тёмный блок на экране и светлый при печати. Длинные строки — проблема серьёзнее цвета. Строка из 120 символов выйдет за поля независимо от темы.
Таблицы. Business добавляет тонированный заголовок; Clean и Academic остаются нейтральными. Широкие таблицы — самая частая проблема при печати. Если в таблице больше пяти-шести столбцов, подумайте о её разделении или уменьшении шрифта в исходнике, а не масштаба печати.
Изображения и бейджи. Темы не меняют отрисовку изображений, но меняют окружающее пустое пространство. Шрифт с засечками в Business может заставить скриншот выглядеть скорее как иллюстрация; шрифт без засечек в Clean делает его частью документации. Сломанные изображения отмечаются в предпросмотре и не прерывают экспорт.
Ссылки. Clean и Business используют синие ссылки; Academic — чёрные; Dark — ярко-синие на экране и чёрные при печати. Если PDF будут печатать в оттенках серого, разница в цвете исчезнет, поэтому делайте текст ссылок описательным, а не полагайтесь на цвет.
Разрывы страниц. Таблица стилей печати по возможности не даёт блокам кода, таблицам, цитатам и изображениям разрываться внутри элемента и удерживает заголовки вместе с последующим содержимым. Это поведение общее для всех тем, но важнее в Academic, где длинный текст создаёт больше переходов между страницами.
Выбор за 30 секунд
Используйте этот короткий путь принятия решения:
- Читатель — инженер, который будет искать команды и код? Выберите Clean.
- Читатель — клиент, руководитель или рецензент, ожидающий отчёт? Выберите Business.
- Документ — длинный текст с небольшим количеством блоков кода? Выберите Academic.
- Вы в основном читаете на экране, а экспортируете потом? Выберите Dark, затем проверьте PDF.
- Всё ещё не уверены? Выберите Clean. Он меньше всего искажает документ.
Полезный тест: экспортируйте первые две страницы в двух темах-кандидатах и прочитайте их на телефоне. Тема, которая выдерживает маленький экран и быстрый просмотр, обычно и есть правильная.
Проверки перед экспортом, которые важнее темы
Ни одна тема не исправит это:
- Иерархия заголовков. Используйте
##для основных разделов и###для подразделов. Пропущенные уровни дают запутанное оглавление. - Длина строк кода. По возможности держите строки в пределах примерно 80–90 символов.
- Ширина таблицы. Меньше столбцов, короче подписи или разделённая таблица.
- Пути к изображениям. Изображения относительно репозитория требуют загрузки репозитория; вставленному Markdown нужны абсолютные URL.
- Конфиденциальный текст. Преобразование локальное, но PDF всё равно можно переслать.
- Размер страницы. A4 и Letter разбиваются на страницы по-разному. Выберите тот, на котором будет печатать получатель.
- Фоновая графика. Включите её, если заливка блоков кода и заголовки таблиц важны для дизайна.
Рекомендация
Для большинства экспортов README Clean — правильный выбор по умолчанию. Он нейтрален, читаем и не притворяется, что документ — что-то другое. Используйте Business, когда PDF — результат для кого-то вне инженерии. Используйте Academic, когда документ предназначен для чтения как текст. Используйте Dark, когда хотите комфортно проверить документ перед созданием итогового светлого PDF.
Тема — это сигнал читателю. Выберите сигнал, соответствующий задаче, а оставшиеся усилия потратьте на содержание: ясное вступление, разумную структуру заголовков и изображения, которые действительно отображаются. Эти решения сохраняются в любой теме.
Полный процесс экспорта см. в руководстве Как преобразовать README с GitHub в PDF. О подготовке под конкретную аудиторию см. 7 практических сценариев превращения README в PDF.
Создайте свой PDF из README
Бесплатно, без регистрации и полностью в браузере.