Markdown и HTML в просмотрщике

Нажмите F3 на файле .md или .html, и он появится отформатированным, а не как исходный текст: заголовки, списки, таблицы, ссылки, списки задач и блоки кода, раскрашенные по языку. Диаграммы, записанные блоком ```mermaid, отрисовываются, а математика между знаками доллара набирается.

Это плагин. Всё на этой странице обеспечивает Markdown and HTML, который можно отключить в Конфигурация ▸ Плагины… — ниже описано, что тогда меняется.

Где появляется отформатированный вид

• Просмотрщик (F3). Отформатированная страница. Меню Вид по-прежнему предлагает Текст, Код и Hex, так что исходный текст в одном щелчке, и имя плагина тоже есть в этом списке.
• Quick View (Ctrl+Q) и информационная страница боковой панели показывают то же самое, так что предпросмотр и полный вид одного файла никогда не расходятся.
• Галерея показывает небольшое изображение начала файла Markdown вместо обычного значка документа.
• Quick Look (Cmd+Y) — собственный предпросмотр macOS, и он не затронут: эта панель принадлежит системе, и ни один плагин не может в ней рисовать.

Структура документа

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

Диаграммы и математика

Блок кода с языком mermaid становится диаграммой; $…$ и $$…$$ становятся набранной математикой. И то и другое отрисовывается на вашем Mac средствами, поставляемыми внутри плагина: ничего не загружается, и никакая часть документа никуда не отправляется. Знак доллара внутри блока кода или встроенного кода остаётся знаком доллара.

Документ без диаграмм и без формул не загружает ни одного из средств, так что обычный README не стоит ничего дополнительно. Диаграмма, которую не удалось прочитать, показывает ошибку там, где был блок, с собственным текстом блока под ней, вместо того чтобы исчезнуть.

И то и другое можно отключить по отдельности в Конфигурация ▸ Настройки ▸ Markdown, где также видно, какая версия используется и откуда она.

Своя версия

Если нужна более новая или другая сборка Mermaid или KaTeX, положите её в папку, которую открывает кнопка Engine Folder…, и будет использована она вместо поставляемой. Имена файлов: mermaid.min.js, katex.min.js, katex.min.css и auto-render.min.js. Из интернета для вас никогда ничего не загружается.

Сделать PDF

Когда курсор стоит на файле .md или .html, Команды ▸ Экспортировать в PDF… — или тот же пункт в контекстном меню панели — записывает документ как PDF рядом с ним, под его собственным именем. Предлагается только в обычных папках — внутри архива или на смонтированном диске нет файла на диске, чтобы прочитать, и нет места рядом, чтобы записать. Отметьте несколько документов, и они будут экспортированы один за другим.

PDF — это та же страница, которую вы видите по F3: та же таблица стилей, тот же раскрашенный код, те же диаграммы и та же математика. Вёрстка по умолчанию на A4 (Letter — это настройка), разрывы страниц приходятся на промежутки между абзацами, пунктами списка и строками таблицы, а не на середину строки текста, и ни одна страница не начинается без заголовка, с которого начинается её раздел. Документ, в котором что-то шире текстовой колонки — таблица со многими столбцами, длинная неразрывная строка — уменьшается, чтобы поместиться, а не обрезается по краю, как это делает и печать в браузере.

На странице настроек плагина, под PDF:

• Бумага — A4 или US Letter.
• Заменять существующий PDF с тем же именем — по умолчанию выключено, поэтому второй экспорт записывается рядом с первым как Name 2.pdf, а не поверх него.
• Показать новый PDF в панели — переводит панель на только что записанный файл. Если это выключено, вы вместо этого получаете короткое сообщение, чтобы экспорт никогда не был безмолвным.

Документ, слишком большой для форматированного вида (см. Пределы), тоже нельзя экспортировать; сообщение его назовёт.

Чего отформатированная страница не сделает

Отформатированная страница намеренно отрезана, потому что файл Markdown — это содержимое, пришедшее откуда-то ещё:

• Она ничего не загружает по сети. Изображение, адрес которого начинается с http, намеренно остаётся пустым: его загрузка сообщила бы тому серверу, когда вы открыли файл и с какого адреса. Изображение, лежащее рядом с документом на диске, загружается обычным образом.
• Собственные скрипты и HTML документа никогда не выполняются. HTML, записанный внутри файла Markdown, показывается как текст, а файл .html отображается с отключёнными скриптами.

Отключение

Отключите плагин в Конфигурация ▸ Плагины…, и файлы .md и .html будут открываться как текст. Структура продолжает работать, подсветка синтаксиса продолжает работать, и больше ничего не меняется — отформатированный вид просто не предлагается. То же самое, если на странице настроек плагина отключить только отформатированный вид.

Ограничения

• Файлы сверх предела размера (по умолчанию 8 МБ, на странице настроек) открываются как текст. Превращать очень большой сгенерированный документ в отформатированную страницу медленно, а текстовый просмотрщик открывает его сразу.
• Отформатированную страницу нельзя редактировать. Для этого используйте F4 или вид Текст для Форматировать, Кодировка и Перейти, которые применимы к исходному тексту, а не к отрисованной странице.