Как преобразовать README с GitHub в PDF (бесплатно, без регистрации)

README пишут для браузера: его прокручивают, из него переходят по ссылкам, и он предполагает, что читатель может щёлкать по репозиторию. Но как только документацию нужно отправить клиенту, приложить к заданию, заархивировать релиз или передать человеку, который не будет клонировать репозиторий, именно PDF становится форматом, который действительно доходит.

Печать страницы GitHub напрямую обычно даёт беспорядок. Навигация сайта, боковые панели и подвал попадают в документ. Широкие блоки кода обрезаются. Относительные изображения ломаются, потому что браузер больше не читает их от корня репозитория. Длинные таблицы неуклюже разрываются между страницами. md2pdf создан, чтобы решить именно эти проблемы, не требуя от вас создавать аккаунт или загружать исходный файл на сервер.

Это руководство проходит весь рабочий процесс — от вставки URL репозитория до проверки экспортированного PDF — и объясняет, что инструмент делает на каждом шаге.

Почему кнопки «Печать» в браузере недостаточно

Веб-интерфейс GitHub — это веб-приложение, а не таблица стилей для печати. Когда вы нажимаете Ctrl+P на странице репозитория, браузер пытается напечатать всю страницу: шапку, дерево файлов, боковую панель «About», виджеты обратной связи и всё остальное, что оказалось в макете. Кое-что можно скрыть с помощью собственной таблицы стилей для печати, но изменить разметку GitHub снаружи нельзя.

Есть ещё три постоянные проблемы:

• Относительные пути к изображениям. README с ![diagram](docs/architecture.png) работает на GitHub, потому что изображение разрешается относительно репозитория. У напечатанной страницы браузера нет надёжного контекста репозитория, поэтому изображение может исчезнуть.
• Широкий код и таблицы. Блоки кода и сравнительные таблицы шире печатной страницы. Без специальных правил для печати они либо уменьшаются до нечитаемого размера, либо обрезаются.
• Разбивка на страницы. Заголовки, блоки кода и строки таблиц должны избегать неудачных разрывов. Обычная печать из браузера редко справляется с этим хорошо.

md2pdf загружает исходный Markdown README, подставляет URL относительно репозитория, отрисовывает Markdown в духе GitHub, очищает результат и применяет таблицу стилей для печати до того, как откроется диалог печати браузера. Результат по-прежнему создаётся встроенным движком «Сохранить как PDF» вашего браузера, но документ, который он получает, уже приведён в порядок.

Что меняет md2pdf

Процесс преобразования полностью выполняется в браузере. На практике:

1. Вы указываете URL публичного репозитория GitHub, локальный файл Markdown или вставленный Markdown.
2. Для репозитория приложение определяет ветку по умолчанию и пробует набор распространённых имён файла README, включая файлы в .github/.
3. Относительные пути к изображениям переписываются на raw.githubusercontent.com, а ссылки в документе — на просмотр blob в GitHub.
4. Markdown отрисовывается с поддержкой GFM: таблицы, списки задач, зачёркивание, блоки кода и автоматические ссылки.
5. HTML очищается с помощью DOMPurify до того, как попадёт в предпросмотр.
6. Оглавление создаётся, когда в документе не меньше трёх заголовков.
7. Применяется таблица стилей печати выбранной темы, и браузер открывает диалог печати.

Ни один файл не загружается. Единственные исходящие запросы — анонимное чтение публичного репозитория, который вы указали, и вызов GitHub API для определения ветки по умолчанию. Приватные репозитории в этой версии не поддерживаются.

Перед началом

Вам понадобится:

• Публичный репозиторий GitHub, локальный файл Markdown или блок Markdown, который можно вставить.
• Современный браузер. Chrome, Edge, Firefox и Safari поддерживают «Сохранить как PDF» в диалоге печати.
• Примерно две минуты для короткого документа — больше, если вы планируете просматривать PDF страница за страницей.

Если репозиторий приватный, загрузка завершится ошибкой. Ручной вариант всё равно работает: скопируйте текст README, вставьте его в редактор и используйте абсолютные URL изображений.

Шаг 1. Укажите инструменту репозиторий

Откройте конвертер и вставьте URL репозитория в поле GitHub repo URL. md2pdf принимает не только канонический URL:

https://github.com/owner/repo
https://github.com/owner/repo.git
github.com/owner/repo
owner/repo
https://github.com/owner/repo/tree/main/docs
https://github.com/owner/repo/blob/main/README.md

Все они ведут к одной и той же паре owner/repo. URL без протокола и сокращение owner/repo удобны, когда вы копируете из терминала или сообщения в чате. Дополнительные сегменты пути принимаются для удобства, но игнорируются: приложение всё равно читает README в корне репозитория на ветке по умолчанию, а не вложенный файл из URL. Если нужен именно вложенный файл, вставьте его Markdown напрямую.

Нажмите Fetch или клавишу Enter. Если поле пустое, приложение скажет, что ожидает, вместо того чтобы молча ничего не делать.

Шаг 2. Дайте ему загрузить и разрешить README

Сначала приложение запрашивает у GitHub API ветку по умолчанию. Затем оно пробует список имён файла README в этой ветке, включая распространённые варианты регистра и расположение .github/README.md. Если сработало ограничение частоты запросов к API, обычная загрузка всё равно может продолжиться — поэтому временный сбой API не всегда завершает работу.

Когда Markdown получен, предпросмотр обновляется. В этот момент стоит проверить три вещи:

• Изображения. Изображения относительно репозитория должны появиться. Если какое-то не появилось, оно может указывать на приватный ресурс, несуществующий путь или абсолютный URL, блокирующий хотлинкинг.
• Блоки кода. Блоки с указанием языка отрисовываются как код. Очень длинные строки будут прокручиваться в предпросмотре, но их всё равно нужно проверить при печати.
• Ссылки. Ссылки в документе переписываются на просмотр blob в GitHub, чтобы оставаться осмысленными в PDF. Внешние ссылки в предпросмотре открываются в новой вкладке.

Если изображение не загрузилось, md2pdf помечает его как сломанное и продолжает. Экспорт не срывается из-за одного недоступного бейджа. Это сделано намеренно: отсутствующий бейдж обычно менее важен, чем остальной документ.

Шаг 3. Выберите тему, подходящую документу

Есть четыре темы печати:

• Clean — тема по умолчанию. Использует нейтральный шрифт без засечек и лучше всего подходит для спецификаций, технических README и документов с большим количеством кода.
• Business использует шрифт с засечками и тёмный блок кода. Подходит для отчётов, предложений и передачи материалов клиентам.
• Academic использует выровненный по ширине текст со шрифтом с засечками и светлым оформлением кода. Создана для длинных текстов, учебных сборников и работ, похожих на статьи.
• Dark — тема, ориентированная на экран. Предпросмотр тёмный для комфортного чтения, а таблица стилей печати принудительно делает текст и фон кода светлыми, чтобы PDF оставался разборчивым.

Для более подробного сравнения см. Clean vs Business vs Academic vs Dark. Для большинства первых экспортов начните с Clean и переключайтесь, только если у документа есть явные ожидания аудитории.

Шаг 4. Решите, помогает ли оглавление

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

Оставьте его, если:

• Документ длиннее нескольких страниц.
• Читателю нужно перейти к конкретному разделу.
• Вы передаёте PDF человеку, который может напечатать только его часть.

Отключите его, если:

• README короткий, и блок содержания добавляет больше шума, чем навигации.
• В документе уже есть оглавление, написанное вручную.
• Вы готовите одностраничную памятку.

Переключатель влияет на предпросмотр и вывод на печать. Отдельной настройки только для PDF нет.

Шаг 5. Напечатайте PDF с правильными настройками

Нажмите Download / Print PDF на панели Live Preview. Приложение вызовет диалог печати браузера. В диалоге:

1. Установите Destination (Принтер) в значение Save as PDF (или эквивалент в вашем браузере).
2. Выберите A4 или Letter в зависимости от региона получателя.
3. Оставьте Margins (Поля) по умолчанию, если у вас нет корпоративного стандарта. Таблица стилей печати уже задаёт поля страницы.
4. Оставьте Scale (Масштаб) на 100% для первой попытки. Если широкая таблица или блок кода обрезается, слегка уменьшите масштаб, а не шрифт в исходнике.
5. Включите Background graphics (Фоновая графика), если браузер это предлагает. Акценты темы, фон блоков кода и заливка заголовков таблиц зависят от фоновых цветов. Без них PDF остаётся читаемым, но темы Business и Dark теряют часть визуальной структуры.
6. Отключите Headers and footers (Колонтитулы) браузера, если вам специально не нужны URL и номера страниц. Они не являются частью дизайна документа.
7. Сохраните файл с описательным именем, например owner-repo-readme-2026-10.pdf.

Точные названия зависят от браузера. В Chrome и Edge фоновая графика находится в разделе «Дополнительные настройки». В Firefox ищите «Печатать фоны». В Safari меньше элементов управления; проверьте предпросмотр перед сохранением.

Шаг 6. Проверьте PDF перед отправкой

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

• Разрывы страниц. Заголовок не должен оставаться один внизу страницы. Блоки кода, таблицы и изображения не должны разрываться посередине.
• Широкое содержимое. Длинные строки кода и таблицы — самые частые виновники переполнения. Если они обрезаны, сократите строки в исходнике или уменьшите масштаб печати.
• Ссылки. Нажмите несколько ссылок в PDF. Ссылки на blob в GitHub должны открывать правильный просмотр файла.
• Изображения. Убедитесь, что схемы и бейджи сохранились. Отсутствующий приватный ресурс сам не появится в PDF.
• Метаданные. Название документа и автор берутся из README и настроек метаданных печати браузера, а не из отдельной формы метаданных PDF. Назовите файл понятно.
• Читаемость. Напечатайте страницу на 100% и проверьте, удобен ли основной текст. Выровненный текст Academic и шрифт с засечками Business могут выглядеть на бумаге иначе, чем на экране.

Если загрузка не удалась

Приложение преобразует ошибки загрузки в понятные сообщения. Типичные случаи:

Что вы видите	Что это обычно значит	Что делать
Репозиторий не найден или приватный	URL неверный или репозиторий требует аутентификации	Проверьте URL; если репозиторий приватный, вставьте Markdown вручную
README не найден	В репозитории нет README в ветке по умолчанию, main или master	Загрузите файл или вставьте Markdown
Достигнут лимит запросов GitHub	Слишком много неаутентифицированных запросов к API	Подождите около минуты и повторите; обычная загрузка может всё ещё работать
Ошибка загрузки или тайм-аут	Проблема с сетью или запрос превысил 15-секундный тайм-аут	Повторите; ручная вставка всё ещё работает

Если загрузка не удалась, редактор сохраняет всё, что вы уже ввели. Можно переключиться на вставку или загрузку файла, не потеряв страницу.

Вставьте или загрузите файл вместо этого

Загрузка с GitHub удобна, но это не единственный способ. Конвертер также поддерживает:

• Загрузку файла .md, .markdown или .txt размером до 2 МБ.
• Вставку Markdown прямо в редактор. Предпросмотр перерисовывается после короткой задержки по мере ввода.
• Загрузку примера, чтобы увидеть, как обрабатываются таблицы, списки задач и блоки кода.

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

Пять исправлений в исходнике, которые улучшают любой экспорт

PDF хорош ровно настолько, насколько хорош Markdown, с которого он начинается. Эти изменения сразу дают результат:

1. Используйте настоящую иерархию заголовков. Начинайте разделы с ##, используйте ### для подразделов и не пропускайте уровни. Оглавление и таблица стилей печати зависят от структуры.
2. Давайте изображениям полезный альтернативный текст. Это полезно для доступности и даёт PDF читаемую замену, когда изображение не загружается.
3. Указывайте язык у блоков кода. Блоки с языком отрисовываются предсказуемее, чем код с отступами, особенно при длинных строках.
4. Делайте таблицы узкими. Таблица из восьми столбцов не поместится на A4 без уменьшения. Перенесите детали в текст или разделите таблицу.
5. Предпочитайте относительные пути для ресурсов репозитория. md2pdf правильно их переписывает. Абсолютные ссылки на локальную машину или приватное хранилище не переживут поездку.

Приватность: что покидает ваш браузер

md2pdf не загружает ваш Markdown. Отрисовка, очистка, создание оглавления и экспорт PDF происходят локально. При загрузке репозитория единственные исходящие запросы — анонимное чтение публичного README и его изображений с GitHub. Нет ни аккаунтов, ни файлов cookie, ни аналитики, связанной с преобразованием.

Это важно, когда документ содержит внутренние заметки, имена клиентов или неанонсированные планы. Вы можете вставить конфиденциальный Markdown и экспортировать его, не отправляя текст стороннему сервису преобразования. То же верно для локальных файлов: файл читает ваш браузер, а не загружает.

Коротко о главном

Вставьте URL публичного репозитория, нажмите Fetch, проверьте предпросмотр, выберите тему, оставьте оглавление для длинных документов и напечатайте PDF с включённой фоновой графикой. Перед отправкой файла проверьте разрывы страниц и широкие блоки кода. Если загрузка не удалась, вставьте или загрузите Markdown и продолжите.

Весь процесс задуман скучным: без аккаунта, очереди, загрузки и серверного рендерера. Просто README, таблица стилей печати и PDF, который можно передать человеку.