Командная строка

slides [deck.md] [flags]
slides [command] [flags] deck.md

Команды

slides <command> --help выводит флаги команды. Флаги могут стоять до или после презентации: slides deck.md -o out.html и slides -o out.html deck.md — одно и то же. Длинные флаги пишутся с двумя дефисами (--html); -o — единственный короткий. build записывает deck.html рядом с deck.md, если -o не указывает иное.

Флаги

Несколько презентаций и каталог

В v0.6.0 build принимает несколько презентаций, каталог (презентации в нём, находимые рекурсивно) или шаблон и собирает до --parallel из них одновременно. - — стандартный ввод; в отличие от marp-cli, из канала ничего не читается, пока этого не скажет -.

Шаблон читается так, как читает glob marp-cli (** и {a,b} в v0.7.0; берите его в кавычки, чтобы оболочка оставила его slides): *, ?, [a-z] и {md,txt} внутри имени, ** для любого числа каталогов, так что 'docs/**/*.md' берёт презентации всего дерева. Подстановочный знак не захватывает имя, начинающееся с точки, в node_modules ничего не ищется, регистр важен (*.md не находит UPPER.MD), а всё, что совпало с шаблоном, конвертируется независимо от расширения. Шаблон, которому ничто не соответствует, — ошибка.

• -I dir находит файлы Markdown (.md, .mdown, .markdown, .markdn, в нижнем регистре) в dir, как это делает marp-cli: в node_modules и каталогах с точкой не ищется. С -o out каждая презентация записывается по своему пути внутри dir, отражённому в out: dir/sub/b.md даёт out/sub/b.html (b.pdf, b.001.png, b.txt, … в зависимости от флагов). Без -o результаты попадают рядом с презентациями. Указать и презентации, и -I — ошибка, как и -o file для нескольких презентаций (-o - разрешён).
• -P n собирает n презентаций одновременно. Отрисовка одной презентации уже использует ядра, поэтому n ограничено их числом; с -o - презентации собираются одна за другой. Сообщения презентации остаются вместе, а презентация, которая не собралась, не останавливает остальные: статус выхода равен 1, а сообщение перечисляет неудачи.

Переходы и страница показа

В v0.6.0 работает директива transition из marp-cli: <!-- transition: fade 1s -->, имя и необязательная длительность, для слайда и следующих за ним, либо <!-- _transition: cover --> для одного. Встроенные имена — те же, что у marp-cli: clockwise, counterclockwise, cover, coverflow, cube, cylinder, diamond, drop, explode, fade, fade-out, fall, flip, glow, implode, in-out, iris-in, iris-out, melt, overlap, pivot, pull, push, reveal, rotate, slide, star, swap, swipe, swoosh, wipe, wiper и zoom; none выключает переход. Страница проигрывает его через View Transition API браузера, когда зритель покидает слайд, у которого он есть, вперёд, и когда возвращается к нему; браузеры без этого API меняют слайды как раньше, а зрителю, попросившему уменьшить анимацию, достаётся простое затухание. Тема может принести собственные keyframes с именами marp-transition-NAME (или marp-outgoing- и marp-incoming-, и -backward), которые используются раньше встроенных.

На странице есть экранный пульт — назад, страница, вперёд, полный экран, — который показывается, когда двигается указатель или нажимается клавиша, и через мгновение прячется (--bespoke.osc=false убирает его), а с --bespoke.progress — индикатор хода. Индикатор хода теперь по умолчанию выключен, как в marp-cli; раньше он рисовался всегда.

Режим докладчика

В v0.7.0 на странице есть режим докладчика marp-cli. Нажмите p или последнюю кнопку пульта — и откроется окно с текущим слайдом, следующим шагом, вашими заметками, страницей, временем и таймером (щелчок по таймеру сбрасывает его; + и - меняют размер заметок; полосу между слайдами и заметками можно перетаскивать). Два окна следуют друг за другом в обе стороны: стрелки, щелчок по следующему шагу или по Previous/Next в любом из них двигает другое, по одному фрагменту.

Он работает так же, как у marp-cli, по его исходникам 4.5.1: окно — это ?view=presenter&sync=KEY того же файла, следующий шаг — та же страница, что ?view=next во фрейме, а окна делят свою позицию через localStorage (bespoke-marp-sync-KEY), так что сервер и сеть не нужны, и он не работает в браузере без localStorage (кнопка об этом сообщает). Заметки — это текст: &, < и > экранируются, так что заметка никогда не может быть разметкой. Они находятся на странице скрытыми, чтобы режим докладчика мог их забрать, и поэтому не попадают в то, что скринридер читает аудитории. У страниц --bare нет ничего из этого. Режим добавляет к странице около 10 КБ.

Режим обзора

В v0.8.0 нажмите o (или Escape: marp-cli переключает обоими), кнопку сетки на пульте или счётчик страниц режима докладчика — и каждый слайд целиком показывается в сетке поверх страницы. Стрелки выбирают слайд (вверх и вниз — по строкам), Home и End переходят к концам, а остальные окна следуют за ним; Enter, Space или щелчок выбирают слайд и, поверх страницы, закрывают обзор. Поверх режима докладчика выбор оставляет его открытым (докладчик выбирает слайд для показа и продолжает смотреть). Кнопка «Close overview», o и Escape закрывают его. Это решение marp-cli: страница, снова во фрейме по адресу ?view=overview&sync=KEY, делящая позицию через localStorage, без сети. Слайды в сетке доступны для фокуса и подписаны «Slide N», а закрытый обзор неактивен, так что пользователи клавиатуры и скринридеров никогда в него не попадают. Два режима вместе добавляют к странице около 15 КБ.

Файлы конфигурации

marp-cli читает свои параметры из файла в рабочем каталоге, и slides тоже, если файл — это данные: .marprc (YAML, JSON — тоже YAML), .marprc.json, .marprc.yaml, .marprc.yml, .config/marprc* или ключ marp в package.json; --config-file (-c) называет любой файл JSON или YAML, например marp.config.json. Ищется только в рабочем каталоге, а не в родительских, как и в поиске marp-cli. Файл JavaScript или TypeScript (marp.config.js …) — это программа, которую slides не запускает: он об этом сообщает и продолжает. Параметры — те из документации marp-cli, что имеют здесь смысл: title, description, author, keywords, url, ogImage, lang, theme, themeSet, html, allowLocalFiles, template, bespoke, inputDir, output, parallel, pdf, pptx, notes, pdfNotes, pdfOutlines, images, image, imageScale, jpegQuality, watch, server, preview; пути отсчитываются от файла. Командная строка главнее. engine, options и browser* требуют движка Marp и браузера и игнорируются с предупреждением, как и флаги --browser*: скрипты, написанные для marp-cli, продолжают работать. (slides.yaml и slides.hcl с kinds и данными шаблонов — отдельные файлы и читаются как раньше.)

Watch, serve и preview

В v0.6.0, с маршрутами и протоколом живой перезагрузки marp-cli (по его исходникам 4.5.1, сверено с работающим marp -s).

slides --server dir (-s) раздаёт каталог по адресу http://127.0.0.1:8080/ (переменная окружения PORT меняет порт; занятый порт — ошибка, которая об этом говорит):

Страница открывает WebSocket на /.__marp-cli-watch-notifier__/<id>, где id — это SHA-256 пути презентации; сервер отправляет ready, затем reload, когда меняется презентация или что-либо в каталоге. Каталог, запрошенный без завершающего слэша, перенаправляется на него (marp-cli отдаёт там свой индекс, что ломает относительные ссылки страницы).

--watch (-w) собирает презентации, затем пересобирает ту, что изменилась, а когда меняется файл --theme-set, файл kinds или данных либо конфигурация — все. Записываемые им страницы открывают сокет на loopback (порт 37717 или следующий свободный) и перезагружаются, когда их презентация собрана заново. Презентация, которая не собралась, фиксируется в отчёте, и наблюдение за ней продолжается. --preview (-p) открывает браузер по умолчанию на сервере или на только что собранных HTML-страницах; собственного окна нет, поскольку у slides нет браузера, которым можно управлять.

Сервер — это путь внутрь машины, поэтому он строже, чем у marp-cli, который слушает на всех интерфейсах и ничего не проверяет:

• он слушает на 127.0.0.1; --host меняет это, с предупреждением, а подстановочный адрес уже не может проверять заголовок Host;
• заголовок Host должен быть loopback-именем (localhost, 127.0.0.1, [::1], *.localhost) или хостом, на котором сервер слушает, что останавливает DNS rebinding;
• Origin WebSocket должен быть собственным у сервера; сокеты режима watch принимают и null-origin страницы, открытой из файла; запрос с другого сайта, не являющийся навигацией (скрипт, изображение, fetch), отклоняется;
• путь очищается, его символические ссылки разрешаются, и результат должен лежать внутри каталога: .. и ссылка наружу отклоняются, как и ?pdf презентации снаружи; имена, начинающиеся с точки (.git, .env), не раздаются;
• только GET и HEAD; несколько конвертаций одновременно; не более 4096 каталогов под наблюдением, и ни одного в node_modules или под точкой.

За обратным прокси --allowed-host name (в v0.14.0, можно повторять) добавляет публичное имя прокси к принимаемым Host и Origin; проверки остаются включёнными, а сервер остаётся на loopback. Самостоятельный хостинг ставит его за Caddy, с HTTPS и входом.

Метаданные страницы

Командная строка главнее презентации, как в marp-cli, где флаги дописываются к презентации как последний комментарий-директива. Правила прочитаны в marp-cli 4.5.1 и закреплены тестами по его выводу (в v0.6.0):

• Презентация без title берёт текст своего первого заголовка самого низкого уровня, как написано (# **Bold** title даёт **Bold** title). Без заголовка <title> нет.
• keywords делятся по запятым, обрезаются и дедуплицируются; список из front matter берётся как есть. Как и marp-cli, страница несёт тег keywords начиная со второго ключевого слова, а не для единственного.
• Недопустимый url (не абсолютный) игнорируется с предупреждением, а прежнее значение сохраняется; допустимый также записывает <link rel="canonical"> и og:url.
• author и description идут со своими двойниками Open Graph; для og:image:alt и большой карточки Twitter нужны и заголовок, и изображение.

Изображения, PDF, PPTX и ODP

-o с расширением .pdf, .pptx, .odp, .png или .jpg выбирает формат, как у marp-cli. Выходные каталоги создаются. В PDF одна страница на слайд, в размере слайда, и оглавление из слайдов и их заголовков.

Заметки и оглавление PDF

В v0.6.0 PDF принимает два параметра marp-cli, и они сверены с PDF, которые marp-cli 4.5.1 пишет для той же презентации:

• --pdf-notes помещает заметки докладчика каждого слайда на его страницу как аннотацию-примечание: жёлтый значок Note внизу слева, содержимое которого — заметки (несколько комментариев соединены пустой строкой), а заголовок — author презентации. Один --pdf-notes запрашивает PDF, как в marp-cli.
• Оглавление содержит полужирную закладку «Page N» для каждого слайда и под ней заголовки слайда, вложенные по уровням (--pdf-outlines.pages и --pdf-outlines.headings выбирают эти две части). Оглавление здесь включено по умолчанию, а в marp-cli выключено. slides всегда его писал; оно стоит несколько сотен байт и делает длинную презентацию навигируемой, поэтому значение по умолчанию остаётся. --pdf-outlines=false или --no-pdf-outlines из marp-cli выключает его, а =false у .pages или .headings убирает эту часть. Закладка заголовка ведёт к его слайду; marp-cli ещё и прокручивает до заголовка.

Отрисовку выполняет go-webengine, а PDF пишет go-pdfkit; шрифты, которые запрашивают встроенные темы (Lato, Roboto Mono), берутся из go-opentype/fonts и встраиваются, так что отрисовка никогда не обращается к сети. Chrome нет.

--image-scale 2 рисует с двумя физическими пикселями на CSS-пиксель. Локальные изображения отклоняются, пока не указан --allow-local-files, и даже тогда читаются только файлы из каталога презентации и ниже: презентация извне не доберётся до ~/.ssh. Несколько фонов и разделённые фоны (![bg left:40%]) рисуются так же, как слои Marp.

--pptx записывает презентацию через WritePresentation из go-ooxml, с заметками докладчика и метаданными презентации. Начиная с v0.5.0 слайды редактируемые (см. ниже); --pptx-raster записывает по одной картинке на весь слайд, как у marp-cli, в масштабе 2 по умолчанию, который переопределяет --image-scale. Результат открывает LibreOffice. Проверялся только LibreOffice; PowerPoint и Keynote — нет.

--odp записывает презентацию OpenDocument через WritePresentation из go-odf, с заметками докладчика; --odp-raster записывает по одной картинке на слайд.

Редактируемые PPTX и ODP

Начиная с v0.5.0 слайды PPTX или ODP редактируемые — PPTX у marp-cli — это одна картинка на слайд, а его экспериментальный --pptx-editable конвертирует PDF через LibreOffice. Здесь каждый слайд рисуется по своей раскладке — той же, по которой рисуют экспорты в PNG и PDF:

• каждая строка текста — это текстовый блок в своей рассчитанной позиции, шрифтами, которыми слайд был рассчитан, — встроенными в файл, так что он выглядит одинаково на машине без Lato или Inter (проверено на LibreOffice 25.8), — с полужирным, курсивом, цветами, межбуквенным интервалом и кликабельными ссылками;
• фоны, границы и скруглённые блоки — это фигуры; градиенты — градиентные заливки в PPTX и картинки в ODP (у градиента ODF два цвета);
• картинки хранятся один раз, сколько бы слайдов их ни показывало;
• то, что слайд выразить не может — элемент под opacity, filter, размытая тень, — это картинка этого элемента, а его текст остаётся поверх неё;
• начиная с v0.15.0 формула, эмодзи или SVG-изображение — это группа векторных фигур (p:grpSp в PPTX, draw:g в ODP), которая перемещается как одно целое. SVG, которому нужны обрезка или радиальный градиент, остаётся картинкой.

При обратной отрисовке LibreOffice слайд отличается от пикселей экспорта в PNG на 0,04–2 %. --pptx-raster и --odp-raster сохраняют по одной картинке на слайд.

Переходы и фрагменты в PDF, PPTX и ODP

Начиная с v0.18.0.

PDF, PPTX и ODP несут то, что проигрывает HTML-страница. Директива transition слайда записывается на следующем слайде, на который он переходит (marp-cli проигрывает директиву слайда при уходе с него), в виде ближайшего эффекта, который есть в формате. Из 33 встроенных переходов marp-cli:

Собственный переход (keyframes темы или слайда) становится fade. Одно предупреждение на экспорт перечисляет замены. Длительности в PPTX сохраняют ближайшую из трёх скоростей PowerPoint; PDF (/D) и тайминг ODP сохраняют точные секунды.

Фрагменты — это построения в редактируемых презентациях, --pptx и --odp: список с фрагментами (пункты, написанные через *) проигрывается по щелчкам, один щелчок на фрагмент, по порядку, и каждый плавно проявляет свой пункт (fade). В PDF они становятся страницами только с --pdf-fragments: одна страница PDF на каждый шаг фрагмента, как наложения Beamer. По умолчанию это выключено, чтобы PDF совпадал с PDF marp-cli, и не сочетается с --pdf-raster.

Это проверено только в LibreOffice. В самом PowerPoint это не проверялось, поэтому не полагайтесь на это там.

Векторный PDF

Начиная с v0.4.0 PDF рисуется векторами: go-webengine рисует рассчитанный слайд в PDF вместо пикселей. Текст — это текст, шрифтами, которыми слайд был рассчитан, встроенными подмножеством с таблицей /ToUnicode — его можно выделять, искать и копировать. Фоны, границы и градиенты — это контуры и затенения, изображение, показанное на многих слайдах, встраивается один раз, а ссылки кликабельны. Презентация из 100 слайдов в тесте производительности занимает 758 КиБ против 837 КиБ у marp-cli и 10 МиБ у PDF из изображений v0.3.0 и записывается за 0,3 с.

Элемент, не имеющий здесь векторной формы, — под opacity < 1, с filter или поворотом, с размытым box-shadow, с градиентом с затухающей непрозрачностью, — рисуется как растр только этого элемента, а его текст кладётся поверх невидимо, чтобы оставаться выделяемым. --pdf-raster записывает по одному изображению на страницу, как v0.3.0.

Начиная с v0.15.0 формулы, эмодзи и SVG-изображения тоже векторные (go-webengine v0.22.0): каждый отдельный рисунок — одна форма-XObject PDF, нарисованная там, где используется, чёткая при любом масштабе.

Доступный размеченный PDF

Начиная с v0.12.0 векторный PDF размечен тегами. Он несёт свою логическую структуру, которую скринридер читает по порядку, как читает веб-страницу:

Файл объявляет PDF/UA-1, стандарт доступного PDF. Он несёт title презентации, который показывает программа просмотра, и её lang (--lang, если презентация его не задаёт, иначе en).

Презентация, проверенная veraPDF, проходит PDF/UA-1, если только её собственные заголовки не нарушают порядок, требуемый стандартом. PDF/UA требует, чтобы первый заголовок был H1 и ни один уровень не пропускался (#, затем ###). Исправить это может только автор презентации. PDF из Chrome той же презентации, который пишет marp-cli, тоже размечен, но нарушает семь правил PDF/UA, не имеет раздела на слайд и формул.

Разметка презентации из 100 слайдов в тесте производительности стоит 4 % по размеру (788 против 757 КиБ) и не даёт измеримой потери времени. --pdf-tags=false записывает PDF без тегов.

slides.yaml

Файл конфигурации рядом с презентацией применяется к ней, так что папка с презентациями делит один:

kinds: kinds.yaml        # a mapping of kinds, or file(s) holding one
themes:                  # theme CSS files or directories
  - themes/
data:                    # template data
  company: Example Inc.
html: false              # allow all raw HTML
lang: en

Kinds: собственные kinds: презентации переопределяют kinds файла и командной строки. Данные: data файла и командной строки переопределяют front matter презентации, так что одну презентацию можно собрать с разными данными.