Печатайте Markdown красиво

Самый быстрый способ попробовать mdprint - начать печатать в редакторе на главной странице. Он открывается с примером документа, в котором задействована каждая функция - таблицы, код, формулы, диаграммы, - чтобы вы сразу увидели, как выглядит готовая страница. Удалите образец и введите свой контент или вставьте его оттуда, где он был написан.

Если у вас уже есть файл Markdown на компьютере, есть два способа его загрузить. Первый - перетащить его из файлового менеджера в панель редактора. Пока вы тащите, вокруг зоны сброса появится подсветка. Отпустите файл, и редактор заполнится его содержимым. Второй - нажать кнопку «Импорт» на панели инструментов и выбрать файл в диалоге. Оба способа читают файл локально - ничего не загружается на сервер.

mdprint принимает файлы .md, .markdown и .txt. Расширение .txt полезно для документов, написанных как Markdown, но сохранённых с общим расширением другим инструментом. Если вы попытаетесь импортировать файл с другим расширением, mdprint покажет ошибку и оставит ваш текущий контент нетронутым.

Если вы никогда раньше не писали на Markdown, правила достаточно малы, чтобы выучить их за пять минут. Вы пишете простой текст, и четыре символа делают большую часть работы. Символ # в начале строки создаёт заголовок - один # для самого большого, шесть ###### для самого маленького. Символы * и _ вокруг слова делают его курсивом с одним по бокам и жирным с двумя. Символ - или * в начале строки создаёт маркер списка. Отступайте на два пробела для вложенности.

Код обрабатывается обратными кавычками. Одна обратная кавычка с каждой стороны фразы оформляет её как `строчный код`. Три обратные кавычки на отдельной строке начинают блок кода, и ещё три - заканчивают. Если поставить имя языка сразу после открывающих трёх кавычек (```python, ```typescript, ```sql), блок кода получит подсветку для этого языка. Без подсказки подсветчик пытается угадать по содержимому, что обычно срабатывает для популярных языков.

Ссылки и изображения используют квадратные скобки и круглые скобки. Ссылка - это [текст, который видите](URL). Изображение - то же самое с восклицательным знаком впереди: . При печати в PDF изображения с URL на публичных серверах будут загружены и встроены. Изображения с локальной машины или из-за авторизации не отобразятся - встраивайте их прямо в редактор как data-URL в base64, если они нужны в тексте.

Таблицы - единственная часть Markdown, которая выглядит громоздко в исходнике, но рендерится чисто. Строка заголовков, строка разделителей из дефисов и одна или несколько строк данных, разделённые вертикальными чертами. Столбцы не обязаны быть выровнены в исходнике - рендерер сам разбирается с отступами. Добавьте двоеточие к одному или обоим концам дефисов в строке разделителей, чтобы управлять выравниванием: :--- для левого, ---: для правого, :---: для центра.

Математические уравнения используют синтаксис TeX в знаках доллара. Один знак доллара с каждой стороны даёт строчную формулу: $a^2 + b^2 = c^2$. Два знака доллара на отдельных строках дают блочное уравнение, центрированное на собственной строке и более крупное. Все ожидаемые команды LaTeX-математики - \frac, \int, \sum, \sqrt, греческие буквы, матрицы, символы AMS - работают, потому что mdprint использует KaTeX, реализующий тот же синтаксис.

Диаграммы используют синтаксис Mermaid внутри блока кода с тегом языка mermaid. Простейшая диаграмма - блок-схема: начните с graph LR (слева направо) или graph TD (сверху вниз), затем напишите узлы, соединённые стрелками. Mermaid также поддерживает диаграммы последовательностей (показ потока сообщений между акторами во времени), диаграммы Ганта (временные шкалы проектов с зависимостями), диаграммы классов (отношения объектов) и диаграммы состояний (конечные автоматы). В документации Mermaid есть примеры на каждый тип.

Сноски позволяют сохранить читаемость прозы, прикрепляя подробные цитаты или замечания. Отметьте сноску в тексте через [^1] (номер может быть любым - они перенумеруются в выводе). Где-то ещё в документе определите сноску через [^1]: содержимое сноски. mdprint собирает все сноски в конце печатного документа и добавляет обратные ссылки, ведущие от каждой сноски к месту её появления в тексте.

Если ваш документ длинный, вставьте буквальный текст [[toc]] в исходник там, где должно появиться оглавление. mdprint заменит его вложенным списком ссылок на каждый H2 и H3 в документе. В печатном PDF то же оглавление становится навигационной структурой, которую могут использовать программы чтения PDF.

Откройте панель «Настройки» на панели инструментов, чтобы управлять генерацией PDF. У размера страницы два варианта: A4 (стандарт за пределами Северной Америки) или Letter (стандарт в Северной Америке). Ориентация переключается между книжной и альбомной - альбомная полезна для документов с широкими таблицами или диаграммами. Поля предлагают три пресета: узкие дают больше полезной области для плотного контента, обычные - общепринятая середина, широкие оставляют место для рукописных пометок на распечатке.

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

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

Кнопка «Печать» открывает встроенный диалог печати браузера. Оттуда каждая современная операционная система предлагает «Сохранить как PDF» в качестве назначения - Chrome, Firefox, Safari и Edge поддерживают это в macOS, Windows и Linux. Прохождение через диалог печати даёт максимум контроля: можно выбрать любой принтер, посмотреть каждую страницу, изменить ориентацию на конкретной странице (если драйвер поддерживает), а на некоторых принтерах - лоток или скрепление.

Кнопка «Скачать PDF» пропускает диалог печати и генерирует PDF-файл прямо в браузере, затем запускает скачивание. Она использует ваши текущие настройки (размер страницы, ориентация, поля) для форматирования. Этот путь быстрее, когда вы точно знаете, чего хотите, и вам не нужна гибкость диалога печати. Он работает так: страница рендерится в изображение высокого разрешения, которое помещается в PDF, поэтому результат всегда совпадает с тем, что вы видите на экране. Компромисс: поскольку страница становится изображением, текст в таком PDF нельзя выделить или искать по нему.

Два пути различаются тем, что в итоге оказывается внутри файла. «Сохранить как PDF» через кнопку «Печать» сохраняет текст как текст: его можно выделять и искать, он остаётся чётким при любом масштабе, а диаграммы остаются векторными. «Скачать PDF», напротив, это моментальный снимок-изображение в один клик, поэтому он быстрый и точный до пикселя, но текст в нём выделить нельзя. Используйте «Сохранить как PDF», когда нужен выделяемый текст или максимально чёткий результат при любом масштабе; используйте «Скачать PDF», когда нужна просто быстрая и точная копия того, что на экране, без открытия диалога печати.

Разрывы страниц в неудобных местах. mdprint избегает разрывов внутри блоков кода, таблиц и диаграмм, но не вмешивается в прозу. Если заголовок попадает в самый низ страницы, а содержание раздела на следующей, самый простой способ - добавить пару предложений выше или ниже, чтобы сместить заголовок. Ручного синтаксиса разрывов страниц в V1 нет - он значится в списке V2.

Изображения не появляются в PDF. Самая частая причина - URL изображения, указывающий на локальную файловую систему (file://) или на сервер, не разрешающий cross-origin-доступ. Либо встраивайте изображение как data-URL прямо в Markdown, либо загрузите его на хост, разрешающий публичное чтение. Imgur, серверы user-content GitHub и большинство CDN работают.

Формулы не рендерятся. Проверьте исходник на неэкранированные знаки доллара в обычном тексте - случайный $ может начать математический фрагмент, который поглотит остаток абзаца. Если нужен буквальный знак доллара в тексте, экранируйте: \$. Если синтаксис формулы корректный, но уравнение всё равно не отображается, возможно, команды LaTeX нет в списке поддерживаемых KaTeX - полный справочник есть в документации KaTeX.

Диаграмма пустая. Mermaid строг к синтаксису. Самые частые ошибки - отсутствующий пробел после graph LR, идентификатор узла, содержащий пробел (используйте camelCase или подчёркивания), либо стрелка, указывающая на неопределённый узел. Откройте консоль разработчика в браузере - Mermaid выводит конкретное сообщение об ошибке при сбое парсинга.

Таблицы переносятся странно. Если таблица шире страницы, mdprint уменьшит её для подгонки. Для очень широких таблиц переключитесь на альбомную ориентацию в настройках или преобразуйте таблицу в список. PDF не умеет горизонтальную прокрутку так, как это делает веб.

Используйте сочетания клавиш. Cmd+P (или Ctrl+P на Windows и Linux) открывает диалог печати. Cmd+S (Ctrl+S) запускает «Скачать PDF». Собственные сочетания браузера для поиска (Cmd+F), перезагрузки (Cmd+R) и масштаба (Cmd+плюс/минус) работают как обычно - не конфликтуют с mdprint.

Начинайте каждый документ с H1. Первый H1 становится предложенным именем PDF, заголовком документа для доступности и заметным заголовком вверху печатной страницы. Если начнёте с H2 или ниже, имя файла откатится к 'document.pdf', и придётся переименовывать вручную после загрузки.

Встраивайте изображения как data-URL, когда важна приватность. Если не хотите, чтобы программа чтения PDF загружала изображения с удалённого сервера при открытии файла, преобразуйте картинку в data-URL base64 и встройте её прямо. У большинства ОС есть встроенный или специализированный инструмент для такой конвертации. Итоговый файл больше, но полностью автономен.

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

Сочетайте Mermaid и код в технической документации. Распространённый шаблон - показать блок-схему процесса, за которой следует реальный код, его реализующий. Markdown позволяет делать оба в одном файле, и mdprint отрисовывает их так, что они чисто печатаются рядом.

Cmd+P или Ctrl+P - открыть диалог печати.

Cmd+S или Ctrl+S - скачать как PDF.

Cmd+B или Ctrl+B в редакторе - сделать выделенный текст жирным.

Cmd+I или Ctrl+I в редакторе - сделать выделенный текст курсивом.

Cmd+/ или Ctrl+/ в редакторе - переключить комментарий для текущей строки (HTML-комментарий в Markdown-контексте).

Esc в редакторе в полноэкранном режиме - выйти из полноэкранного режима.