Riga di comando

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

Comandi

slides <command> --help stampa i flag di un comando. I flag possono stare prima o dopo la presentazione: slides deck.md -o out.html e slides -o out.html deck.md sono equivalenti. I flag lunghi prendono due trattini (--html); -o è l’unico corto. build scrive deck.html accanto a deck.md salvo diversa indicazione di -o.

Flag

Più presentazioni, e una cartella

Nella v0.6.0 build accetta più presentazioni, una cartella (le presentazioni al suo interno, trovate ricorsivamente) o un pattern, e ne compila fino a --parallel contemporaneamente. - è lo standard input; a differenza di marp-cli, una pipe non viene letta se non lo dice -.

Un pattern è letto come lo legge il glob di marp-cli (** e {a,b} nella v0.7.0; mettilo tra virgolette perché la shell lo lasci a slides): *, ?, [a-z] e {md,txt} all’interno di un nome, ** per un numero qualsiasi di cartelle, così 'docs/**/*.md' prende le presentazioni dell’albero. Un carattere jolly non raggiunge un nome che inizia con un punto, nulla viene cercato in node_modules, le maiuscole contano (*.md non trova UPPER.MD), e tutto ciò che un pattern individua viene convertito, qualunque sia la sua estensione. Un pattern che non individua nulla è un errore.

• -I dir trova i file Markdown (.md, .mdown, .markdown, .markdn, in minuscolo) sotto dir, come fa marp-cli: node_modules e le cartelle che iniziano con un punto non vengono esplorate. Con -o out, ogni presentazione viene scritta al suo percorso sotto dir, riprodotto sotto out: dir/sub/b.md dà out/sub/b.html (b.pdf, b.001.png, b.txt, … qualunque cosa dicano i flag). Senza -o gli output vanno accanto alle loro presentazioni. Nominare presentazioni oltre a -I è un errore, e lo è anche -o file per più presentazioni (-o - è consentito).
• -P n compila n presentazioni contemporaneamente. Il rendering di una presentazione usa già i core, quindi n è limitato al loro numero; con -o - le presentazioni sono compilate una dopo l’altra. I messaggi di una presentazione restano insieme, e una presentazione che fallisce non ferma le altre: lo stato di uscita è 1 e il messaggio elenca i fallimenti.

Transizioni e pagina di presentazione

Nella v0.6.0 la direttiva transition di marp-cli funziona: <!-- transition: fade 1s -->, un nome e una durata facoltativa, per la slide e per quelle successive, oppure <!-- _transition: cover --> per una sola. I nomi integrati sono quelli di 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 e zoom; none la disattiva. La pagina la esegue con la View Transition API del browser quando lo spettatore lascia la slide che la possiede, avanzando, e quando vi ritorna; i browser senza l’API cambiano slide come prima, e uno spettatore che chiede di ridurre il movimento ottiene una semplice dissolvenza. Un tema può portare keyframe propri, chiamati marp-transition-NAME (o marp-outgoing- e marp-incoming-, e -backward), che vengono usati prima di quelli integrati.

La pagina ha il controller a schermo — precedente, pagina, successiva, schermo intero — che compare quando si muove il puntatore o un tasto e si nasconde dopo un momento (--bespoke.osc=false lo rimuove), e, con --bespoke.progress, una barra di avanzamento. La barra di avanzamento è ora disattivata per impostazione predefinita, come in marp-cli; prima era sempre disegnata.

Vista del relatore

Nella v0.7.0 la pagina ha la vista del relatore di marp-cli. Premi p, o l’ultimo pulsante del controller, e si apre una finestra con la slide corrente, il passo successivo, le tue note del relatore, la pagina, l’ora e un timer (fai clic sul timer per azzerarlo; + e - ridimensionano le note; la barra tra le slide e le note si può trascinare). Le due finestre si seguono a vicenda in entrambe le direzioni: i tasti freccia, un clic sul passo successivo o su Previous/Next in una delle due spostano l’altra, un frammento alla volta.

Funziona come quella di marp-cli, letta dai suoi sorgenti 4.5.1: la finestra è ?view=presenter&sync=KEY dello stesso file, il passo successivo è la stessa pagina di ?view=next in un frame, e le finestre condividono la loro posizione tramite localStorage (bespoke-marp-sync-KEY), quindi non richiede server né rete, e non funziona in un browser privo di localStorage (il pulsante lo dice). Le note sono testo: &, < e > hanno l’escape, quindi una nota non può mai essere markup. Sono nella pagina, nascoste, perché la vista del relatore le prelevi, il che le tiene fuori da ciò che uno screen reader legge al pubblico. Le pagine --bare non hanno nulla di tutto ciò. La vista aggiunge circa 10 KB a una pagina.

Vista panoramica

Nella v0.8.0, premi o (o Escape: marp-cli alterna con entrambi), il pulsante a griglia del controller, o il contatore di pagina della vista del relatore, e ogni slide appare intera in una griglia sopra la pagina. I tasti freccia scelgono una slide (su e giù per riga), Home e End vanno alle estremità, e le altre finestre seguono; Enter, Space o un clic scelgono una slide e, sopra la pagina, chiudono la panoramica. Sopra la vista del relatore una scelta la lascia aperta (il relatore sceglie la slide da mostrare, e continua a guardare). Il pulsante “Close overview”, o e Escape la chiudono. È quella di marp-cli: la pagina di nuovo in un frame a ?view=overview&sync=KEY, che condivide la posizione tramite localStorage, senza rete. Le slide nella griglia sono attivabili con il focus ed etichettate “Slide N”, e la panoramica chiusa è inerte, così gli utenti di tastiera e screen reader non vi finiscono mai dentro. Le due viste insieme aggiungono circa 15 KB a una pagina.

File di configurazione

marp-cli legge le proprie opzioni da un file nella cartella di lavoro, e lo fa anche slides, quando il file è dati: .marprc (YAML, anche JSON è YAML), .marprc.json, .marprc.yaml, .marprc.yml, .config/marprc*, o la chiave marp di package.json; --config-file (-c) nomina qualsiasi file JSON o YAML, marp.config.json per uno. Si cerca solo nella cartella di lavoro, non nelle sue superiori, come fa la ricerca di marp-cli. Un file JavaScript o TypeScript (marp.config.js …) è un programma, che slides non esegue: lo dice e prosegue. Le opzioni sono quelle della documentazione di marp-cli che hanno senso qui: 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; i percorsi sono relativi al file. La riga di comando prevale. engine, options e browser* richiedono il motore di Marp e un browser, e vengono ignorate con un avviso, come i flag --browser*: gli script scritti per marp-cli continuano a funzionare. (slides.yaml e slides.hcl, con i kinds e i dati dei template, sono separati e letti come prima.)

Watch, server e anteprima

Nella v0.6.0, con le rotte e il protocollo di ricaricamento in tempo reale di marp-cli (letti dai suoi sorgenti 4.5.1 e confrontati con un marp -s in esecuzione).

slides --server dir (-s) serve la cartella su http://127.0.0.1:8080/ (la variabile d’ambiente PORT cambia la porta; una porta già in uso è un errore che lo dice):

Una pagina apre un WebSocket verso /.__marp-cli-watch-notifier__/<id>, dove l’id è lo SHA-256 del percorso della presentazione; il server invia ready, poi reload quando la presentazione, o qualsiasi cosa sotto la cartella, cambia. Una cartella richiesta senza la barra finale viene reindirizzata ad essa (marp-cli serve lì il suo indice, il che rompe i link relativi della pagina).

--watch (-w) compila le presentazioni, poi ricompila quella che cambia e, quando cambia un file --theme-set, un file di kinds o di dati o la configurazione, tutte. Le pagine che scrive aprono un socket sul loopback (porta 37717, o la successiva libera) e si ricaricano quando la loro presentazione viene compilata di nuovo. Una presentazione che non si compila viene segnalata e continua a essere osservata. --preview (-p) apre il browser predefinito sul server, o sulle pagine HTML appena compilate; non c’è una finestra propria, dato che slides non ha un browser da pilotare.

Il server è un modo di entrare nella macchina, quindi è più rigoroso di quello di marp-cli, che ascolta su ogni interfaccia e non controlla nulla:

• ascolta su 127.0.0.1; --host lo cambia, con un avviso, e un indirizzo jolly non può più controllare l’header Host;
• l’header Host deve essere un nome di loopback (localhost, 127.0.0.1, [::1], *.localhost) o l’host su cui ascolta, il che impedisce il DNS rebinding;
• l’Origin di un WebSocket deve essere quello del server stesso; i socket della modalità watch accettano anche l’origine null di una pagina aperta da un file; una richiesta da un altro sito che non sia una navigazione (uno script, un’immagine, un fetch) viene rifiutata;
• un percorso viene ripulito, i suoi collegamenti simbolici risolti, e il risultato deve essere dentro la cartella: .. e un collegamento che ne esce vengono rifiutati, così come ?pdf di una presentazione esterna; i nomi che iniziano con un punto (.git, .env) non vengono serviti;
• solo GET e HEAD; poche conversioni contemporanee; al massimo 4096 cartelle osservate, e nessuna in node_modules o sotto un punto.

Dietro un reverse proxy, --allowed-host name (nella v0.14.0, ripetibile) aggiunge il nome pubblico del proxy agli Host e Origin accettati; i controlli restano attivi e il server resta sul loopback. Self-hosting lo mette dietro Caddy, con HTTPS e un accesso.

Metadati della pagina

La riga di comando prevale sulla presentazione, come in marp-cli, dove i flag vengono aggiunti alla presentazione come un ultimo commento-direttiva. Regole lette da marp-cli 4.5.1 e fissate da test rispetto al suo output (nella v0.6.0):

• Una presentazione che non imposta alcun title prende il testo del suo primo titolo di livello più basso, com’è scritto (# **Bold** title dà **Bold** title). Senza titoli non c’è <title>.
• Le keywords sono divise alle virgole, ripulite e deduplicate; un elenco nel front matter viene preso così com’è. Come marp-cli, la pagina porta il tag keywords dalla seconda parola chiave in poi, non per una sola.
• Un url non valido (non assoluto) è ignorato con un avviso, e il valore precedente viene mantenuto; uno valido scrive anche <link rel="canonical"> e og:url.
• author e description arrivano con i loro gemelli Open Graph; og:image:alt e la Twitter card grande richiedono sia un titolo sia un’immagine.

Immagini, PDF, PPTX e ODP

-o con un’estensione .pdf, .pptx, .odp, .png o .jpg sceglie il formato, come fa marp-cli. Le cartelle di output vengono create. Un PDF ha una pagina per slide, alla dimensione della slide, e un indice delle slide e dei loro titoli.

Note e indice del PDF

Nella v0.6.0 il PDF accetta le due opzioni di marp-cli, e vengono confrontate con i PDF che marp-cli 4.5.1 scrive per la stessa presentazione:

• --pdf-notes mette le note del relatore di ogni slide sulla sua pagina come annotazione di nota: un’icona Note gialla in basso a sinistra il cui contenuto sono le note (più commenti uniti da una riga vuota) e il cui titolo è l’author della presentazione. --pdf-notes da solo richiede un PDF, come in marp-cli.
• L’indice contiene un segnalibro in grassetto “Page N” per slide e, sotto di esso, i titoli della slide annidati per livello (--pdf-outlines.pages e --pdf-outlines.headings scelgono le due parti). L’indice è attivo per impostazione predefinita qui e disattivato in marp-cli. slides ne ha sempre scritto uno; costa poche centinaia di byte e rende navigabile una presentazione lunga, quindi il valore predefinito resta. --pdf-outlines=false, o --no-pdf-outlines di marp-cli, lo disattiva, e =false su .pages o .headings elimina quella parte. Un segnalibro di titolo salta alla sua slide; marp-cli scorre anche fino al titolo.

Il rendering è fatto da go-webengine e il PDF è scritto da go-pdfkit; i font richiesti dai temi integrati (Lato, Roboto Mono) provengono da go-opentype/fonts e sono incorporati, così nessun rendering tocca la rete. Non c’è Chrome.

--image-scale 2 esegue il rendering a due pixel del dispositivo per pixel CSS. Le immagini locali vengono rifiutate se non si passa --allow-local-files, e anche allora vengono letti solo i file sotto la cartella della presentazione: una presentazione proveniente da altrove non può raggiungere ~/.ssh. Sfondi multipli e divisi (![bg left:40%]) vengono resi come i livelli di Marp.

--pptx scrive la presentazione con il WritePresentation di go-ooxml, con le note del relatore e i metadati della presentazione. Dalla v0.5.0 le slide sono modificabili (vedi sotto); --pptx-raster scrive una sola immagine a tutta slide per slide, come fa marp-cli, a una scala che per impostazione predefinita è 2 e che --image-scale sostituisce. LibreOffice apre il risultato. È stato provato solo LibreOffice; PowerPoint e Keynote no.

--odp scrive una presentazione OpenDocument, tramite il WritePresentation di go-odf, con le sue note del relatore; --odp-raster scrive un’immagine per slide.

PPTX e ODP modificabili

Dalla v0.5.0 le slide di un PPTX o di un ODP sono modificabili — il PPTX di marp-cli è un’immagine per slide, e il suo sperimentale --pptx-editable converte un PDF tramite LibreOffice. Qui ogni slide è disegnata a partire dal suo layout, quello che disegnano le esportazioni PNG e PDF:

• ogni riga di testo è una casella di testo nella posizione calcolata, nei font con cui la slide è stata impaginata — incorporati nel file, così appare identica su una macchina senza Lato o Inter (verificato con LibreOffice 25.8) — con grassetto, corsivo, colori, spaziatura tra le lettere e link cliccabili;
• sfondi, bordi e riquadri arrotondati sono forme; i gradienti sono riempimenti a gradiente nel PPTX e immagini nell’ODP (un gradiente ODF ha due colori);
• le immagini vengono memorizzate una volta sola, per quante slide le mostrino;
• ciò che una slide non può esprimere — un elemento sotto opacity, un filter, un' ombra sfocata — è un’immagine di quell’elemento, con il suo testo mantenuto sopra;
• dalla v0.15.0 una formula, un’emoji o un’immagine SVG è un gruppo di forme vettoriali (p:grpSp nel PPTX, draw:g nell’ODP) che si sposta come un tutt’uno. Un SVG che richiede un ritaglio o un gradiente radiale resta un’immagine.

Rese di nuovo da LibreOffice, una slide è entro lo 0,04–2 % dei pixel dell’esportazione PNG. --pptx-raster e --odp-raster mantengono un’immagine per slide.

Transizioni e frammenti nel PDF, nel PPTX e nell’ODP

Dalla v0.18.0.

Il PDF, il PPTX e l’ODP portano con sé ciò che la pagina HTML riproduce. La direttiva transition di una slide viene scritta sulla slide successiva, quella su cui entra (marp-cli riproduce la direttiva di una slide quando la lascia), come l’effetto più vicino che il formato possiede. Delle 33 transizioni integrate di marp-cli:

Una transizione personalizzata (i keyframe propri di un tema o di una slide) diventa un fade. Un solo avviso per esportazione elenca le sostituzioni. Le durate mantengono la più vicina delle tre velocità di PowerPoint in un PPTX; un PDF (/D) e la temporizzazione di un ODP mantengono i secondi esatti.

I frammenti sono animazioni nelle presentazioni modificabili, --pptx e --odp: un elenco a frammenti (voci scritte con *) si riproduce con i clic, un clic per frammento, in ordine, e ognuno fa comparire la sua voce in dissolvenza. Nel PDF diventano pagine solo con --pdf-fragments: una pagina PDF per ogni passo di frammento, come le sovrapposizioni di Beamer. È disattivato per impostazione predefinita, perché il PDF coincida con quello di marp-cli, e non si combina con --pdf-raster.

Questo è stato verificato solo in LibreOffice. Non è stato verificato in PowerPoint stesso, quindi non ci si faccia affidamento lì.

PDF vettoriale

Dalla v0.4.0 il PDF è disegnato in vettoriale: go-webengine dipinge la slide impaginata nel PDF invece che in pixel. Il testo è testo, nei font con cui la slide è stata impaginata, incorporati come sottoinsieme con una mappa /ToUnicode — può essere selezionato, cercato e copiato. Sfondi, bordi e gradienti sono tracciati e sfumature, un’immagine mostrata in molte slide viene incorporata una volta sola, e i link sono cliccabili. La presentazione di benchmark da 100 slide pesa 758 KiB, contro 837 KiB di marp-cli e 10 MiB del PDF a immagini della v0.3.0, e viene scritta in 0,3 s.

Un elemento senza forma vettoriale qui — sotto opacity < 1, con un filter o una rotazione, un box-shadow sfocato, un gradiente la cui opacità sfuma — è disegnato come bitmap di quel solo elemento, con il suo testo sovrapposto in modo invisibile perché resti selezionabile. --pdf-raster scrive un’immagine per pagina, come faceva la v0.3.0.

Dalla v0.15.0, anche formule, emoji e immagini SVG sono vettori (go-webengine v0.22.0): ogni disegno distinto è un form XObject PDF, dipinto dove viene usato, nitido a qualsiasi zoom.

PDF accessibile e con tag

Dalla v0.12.0 il PDF vettoriale ha i tag. Porta la propria struttura logica, che uno screen reader legge in ordine, come legge una pagina web:

Il file dichiara PDF/UA-1, lo standard per il PDF accessibile. Porta il title della presentazione, che il visualizzatore mostra, e il suo lang (--lang quando la presentazione non ne imposta uno, en altrimenti).

Una presentazione verificata con veraPDF supera PDF/UA-1, a meno che i suoi stessi titoli violino l’ordine dello standard. PDF/UA richiede che il primo titolo sia un H1 e che nessun livello sia saltato (# poi ###). Solo l’autore della presentazione può correggerlo. Anche il PDF di Chrome per la stessa presentazione, che scrive marp-cli, ha i tag, ma non supera sette regole di PDF/UA, non ha una sezione per slide né formule.

Aggiungere i tag alla presentazione di benchmark da 100 slide costa il 4% in dimensione (788 contro 757 KiB) e nessun tempo misurabile. --pdf-tags=false scrive il PDF senza tag.

slides.yaml

Un file di configurazione accanto alla presentazione si applica ad essa, così una cartella di presentazioni ne condivide uno:

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: i kinds: della presentazione prevalgono su quelli del file e della riga di comando. Dati: i data del file e della riga di comando prevalgono sul front matter della presentazione, così una presentazione può essere compilata con dati diversi.