Формат MD (Markdown)
MD — обычный текстовый файл, в котором решётка означает заголовок, звёздочки — выделение, дефис — пункт списка. Никаких сведений о размере листа, шрифте и полях внутри нет, поэтому вида у документа тоже нет: его придумывает та программа, которая разметку отображает. Печать всегда идёт в два шага — сначала разметка превращается в HTML, потом HTML печатает браузерный движок. Именно поэтому один файл даёт разные PDF в разных программах.
Коротко о цифрах
- Что это за файл
- простой текст, обычно в кодировке UTF-8
- Спецификация
- CommonMark; диалект GitHub добавляет таблицы и списки задач
- Чего в формате нет
- размера листа, полей, шрифта и разрывов страниц
- Путь до печати
- разметка → HTML → печать браузерным движком
- Наши маршруты
- .md не принимают, нужен .html или .htm
Разметка и формат документа — разные вещи
Markdown сообщает смысл: вот заголовок второго уровня, вот цитата, вот блок кода. Он не говорит «шрифт 18 пунктов, отбивка сверху 12». Всё это добавляет отображающая программа своими стилями, и меняются они от программы к программе, от темы к теме и от версии к версии.
У такого устройства есть сильная сторона: файл читается глазами без всяких приложений, хорошо ложится в систему контроля версий и не ломается от переноса между операционными системами. И есть слабая: пока разметка не превращена в HTML с конкретными стилями, вы не управляете ни разбивкой на страницы, ни полями, ни тем, где разорвётся таблица.
Диалекты, из-за которых файл выглядит иначе
- Базовые правила закреплены спецификацией CommonMark — она устраняет разночтения исходного описания.
- Диалект GitHub добавляет таблицы, зачёркивание, списки задач и автоматические ссылки.
- Сноски, блок метаданных в начале файла и математические формулы — расширения, которых в базовом наборе нет.
- Отсюда типичная неприятность: таблица, набранная по правилам одного диалекта, в строгом отображении остаётся строчками с вертикальными чертами.
- Вложенные списки чувствительны к числу пробелов: два и четыре пробела разные отображатели трактуют по-разному.
Что происходит при печати
- Программа переводит разметку в HTML: решётка становится тегом заголовка, звёздочки — тегом выделения.
- К этому HTML применяются её собственные стили — шрифт, кегль, ширина колонки, поля.
- Браузерный движок печатает получившуюся страницу и режет её на листы там, где кончается высота.
- Разрыв попадает куда попадёт: длинный блок кода и широкая таблица рвутся посередине.
- Смените программу — получите другие стили и другое число страниц из того же самого файла.
Предсказуемый путь до PDF
- Экспортируйте разметку в HTML любым редактором или генератором сайта — этот шаг остаётся за вами.
- Соберите всё в один файл: стили в тег style, изображения в base64 или по абсолютным адресам.
- Задайте разбивку явно правилами печати в стилях, если важно, где кончается страница.
- Загрузите .html к нам: получите A4 с полями 0,4 дюйма и напечатанными фонами блоков кода.
- Файла .md ни один наш маршрут не принимает — он будет отклонён по расширению.
Частые вопросы
Почему PDF из одного и того же файла выглядит по-разному?
Потому что вид задаёт не разметка, а стили отображающей программы. Редактор, генератор сайта и просмотрщик применяют разные шрифты и ширины колонки, отсюда разное число страниц и разные места разрывов.
Можно ли загрузить .md к вам напрямую?
Нет, маршрут принимает только .html и .htm. Сначала экспортируйте разметку в HTML в том редакторе, где вы её пишете, а печать этого HTML в PDF сделаем мы.
Что будет, если просто переименовать .md в .html?
Файл загрузится, потому что содержимое HTML по первым байтам не проверяется. Но тегов внутри нет, поэтому в PDF вы увидите сплошной текст со значками разметки: заголовки останутся строками с решётками.
Как задать поля и размер листа?
Правилами печати в стилях внутри самого HTML — они позволяют указать формат листа, ориентацию и отступы. Если ничего не указано, применяется наша настройка: A4 в книжной ориентации с полями 0,4 дюйма.