Командний рядок

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 міняють слайди як раніше, а глядач, який просить зменшити анімацію, отримує простий fade. Тема може принести власні 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 і даними шаблону, окремі й читаються як раніше.)

Спостереження, сервер і попередній перегляд

У 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 має бути власним для сервера; сокети режиму спостереження також приймають походження null сторінки, відкритої з файла; запит з іншого сайту, що не є навігацією (скрипт, зображення, fetch), відхиляється;
• шлях очищується, його символічні посилання розв’язуються, і результат має бути всередині теки: .. і посилання назовні відхиляються, так само як і ?pdf презентації ззовні; імена, що починаються з крапки (.git, .env), не віддаються;
• лише GET і HEAD; кілька перетворень одночасно; не більше 4096 тек спостерігається, і жодної в node_modules чи під крапкою.

За зворотним проксі --allowed-host name (у v0.14.0, можна повторювати) додає публічне ім’я проксі до прийнятних Host та Origin; перевірки залишаються ввімкненими, а сервер лишається на loopback. Self-hosting ставить його за 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 слайд відрізняється в межах 0,04–2 % пікселів від експорту PNG. --pptx-raster та --odp-raster зберігають одну картинку на слайд.

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

Ще не випущено: з’явиться в наступній версії після v0.17.1.

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 презентації, тож одну презентацію можна зібрати з різними даними.