orz-slides — decks & layouts
This page describes orz-slides 1.1 (orz-slides-browser 1.1), which embeds orz-markdown 2.5
Markdown that edits itself, as a slide deck. This page describes orz-slides 1.1: the text twin and its file, presenting, the two ways to edit, the header, the layout grammar, template pages, themes, fit, printing and the CLI. Part of the orz editable-document family, with orz-mdhtml (documents) and orz-paged (print). New to the words "text twin", "assemble" or "shell"? See the guide's short glossary.
orz-slides new
--template talk, or New document in the file), shape slides with the layout editor, and for
anything beyond that ask an AI agent to write or restructure the text. Point it at the
orz-slides agent skill
(orz-slides-skills/SKILL.md)
and describe what you want — “turn these notes into a ten-slide talk,” “make this a
two-column slide with the chart on the right,” “check that every slide fits.” This page is the
reference the agent (and curious humans) can draw on; skim it, don't memorize it.
A text twin and a self-editing file
A deck is its text twin — talk.slides.md, Markdown with a small header and comment
markers that start slides and split them into boxes — and its self-editing file
talk.slides.html, one HTML page that presents the deck in any browser (keys, overview,
speaker view, timer, full screen), edits itself — the whole deck as text beside a live preview, or
one slide at a time with a layout editor — saves back in place and prints one slide per page. The
file is always assemble(text): the exact text rides inside it, everything else is a shell that can be
regenerated, and orz-slides extract gives the text back byte for byte. Keep the
.slides.md in your repository; make the .slides.html whenever someone needs a file.
The deck in the page
Every slide at its logical size — 1280 × 720 (16:9) or 960 × 720 (4:3) — scaled to the window, on the theme's surround. reveal.js 5.2.1 does the deck mechanics.
Nothing is cut silently
Every box — layout boxes, titles, template
pages, floats — shrinks its content to fit, down to 60 %. Past that it is marked clipped, and the editor and
orz-slides inspect --layout say so.
One family
The same text twin, pencil, editor, saving, quiet update, host protocols and CLI as orz-mdhtml and orz-paged 1.0 — built on the orz-markdown carrier kit (text format 1). What slides adds is slides.
Published on npm as orz-slides (CLI and Node
library: import { assemble, extract, inspect, newDocument, upgrade } from 'orz-slides') and
orz-slides-browser (engine and editor component), always the same version. Try the
official blank .slides.html
starter.
Create and build with the CLI
Node 20.16 or newer; nothing to install with npx:
npx orz-slides@1 new talk.slides.md --template talk --title "RAFT in five minutes" --theme nocturne # a new text twin # edit talk.slides.md (by hand or with an agent), then: npx orz-slides@1 inspect talk.slides.md --layout # does every box fit? npx orz-slides@1 talk.slides.md # → talk.slides.html
| Command | What it does |
|---|---|
orz-slides new [x.slides.md] [--template id] [--title T] [--theme id] [--ratio 16:9|4:3] [--html] [--cdn] | writes a new text twin from a deck template (default starter): its header with carrier: slides and a fresh uid, then the template's slides; --html also assembles it; without a file name the text goes to stdout |
orz-slides assemble x.slides.md [-o out] [--cdn | --inline] [--resolve-includes | --no-includes] [--replaces sha256] | writes x.slides.html from the text — the same bytes every time (also: orz-slides x.slides.md). Keeps the existing file's delivery and the includes it recorded; --resolve-includes reads {{md part.md}} files from the text's folder (never outside it), and an include left out shows an "Included file not available" note. Every slide needs a <!-- slide --> line: a x.slides.md without one assembles, with a warning, into a deck with no slides; a plain x.md without one (and without carrier: slides in a header) is refused as an orz-mdhtml document — --force makes a deck of it as it is |
orz-slides extract x.slides.html [-o out] [--replaces sha256] | writes the exact text twin back out of a file — also of a page the browser saved |
orz-slides upgrade old.slides.html [--text t | --no-text] [--cdn | --inline] · orz-slides upgrade deck.md | turns a 0.x file (or an older 1.x shell) into a 1.0 file and writes its text twin; a 0.x deck source into a format-1 text — with a report of what changed |
orz-slides inspect <file> [--layout [--offline]] | says what any text or file is — version, settings, slides, lint, whether its twin matches — and what to do next; --layout renders the deck in your installed Chrome and reports, per slide and box, the fit scale and whether anything is cut |
orz-slides themes · orz-slides templates | list the slide themes and the deck templates |
Content — title, theme, ratio, footer — comes only from the text's header;
assemble has no content options. Every command takes --json (one object with a stable
reason and a next step on refusals), and nothing that could hold other work (a file saved
in the browser, an edited twin) is overwritten without --force, which keeps a <file>~
backup — unless what it replaces is a known earlier state: what the CLI itself last wrote or read
for that pair, or a committed version of the twin in git (glossary). The robust
way for scripts and agents: assemble, extract (to a file), inspect and upgrade print the
sha256 of the text they wrote or read (so does every --json result that wrote a text;
new only with --json); pass it back as --replaces <sha256>
and the file is replaced only while it still holds that text. Exit status: 0 done, 1 refused or failed, 2 usage
error.
Delivery. Files are inline by default: the engine, reveal.js and the 14 themes
are inside the file (about 2.2 MB), so it opens and presents without fetching the engine. --cdn
writes a small file for decks you publish on the web; it loads the engine from jsDelivr,
https://cdn.jsdelivr.net/npm/orz-slides-browser@<version>/orz-slides.browser.js (the file's own
version, e.g. @1.0.0).
The themes ship inside the engine, so a --cdn file styles exactly like an inline one. Either way, the
themes' webfonts, KaTeX, the content libraries (Mermaid, SMILES, Chart.js) and the editor load from CDNs the first
time; without a network the deck still presents, in system fonts.
In the file: present, and one quiet pencil
A .slides.html opens as its deck. → ↓
Space PageDown N go forward,
← ↑ PageUp
Shift Space P Backspace back,
Home / End to the ends. A small pencil sits at the bottom-left:
click it to edit; hover it (tap on a touch screen) for everything else — Present,
Overview, Speaker view, Print, Save and the deck's settings are
all in its list. A dot on the pencil means unsaved changes.
Present
Present
(F, from the pencil's list) shows the deck alone, full screen; Overview
(O) shows every slide — Enter or Esc
closes it; Esc also leaves Present, and otherwise opens the overview.
Speaker view (S) opens its own window with the current and next slide,
the notes, a clock and a timer with Pause and Reset (if the browser blocks the pop-up, allow
pop-ups for the page and press S again); T toggles the timer. A
slide's step option reveals its points one at a time.
Settings are the deck's
Theme, Ratio, Slide numbers, Progress bar and Section numbers in the pencil's list (or the editor's bar) write the text's header — one undoable edit, unsaved until you Save — and the deck follows.
Print prints one slide per page at the slide's size, every step shown; Print with notes puts each slide over its speaker notes. Choose Save as PDF in the dialog for a PDF. What does not fit on paper is marked on its page and said.
Save, New, Copy
Save
(Ctrl/⌘ S) writes assemble(text) — never the rendered deck — back to the
file, and asks before it overwrites a file that changed on disk. Also: Download a copy, New
document (from the minimal deck template) and Save as new copy, both with this
version's shell.
A local file checks at most once a day for a newer engine; the pencil then offers Update to x.y.z, which re-assembles the same text with the new release (verified by SHA-384). Nothing changes until the reader asks.
Two ways to edit
The pencil (or Ctrl/⌘ E) opens the editor. Both ways edit the one text, with one undo history.
The whole deck, with the live card
CodeMirror beside a flattened preview: every slide's content in order, a thin divider per slide with its number, title and layout, boxes labelled, notes and footers set apart. In its corner, the live slide card shows the slide under the caret as it presents, with a badge — fits, shrunk to 80%, footer cut, cut on paper. Issues lists the deck's lints with quick fixes. Fold the card to a tab when it is in the way.
One slide at a time
The card's Edit (Ctrl/⌘ ⇧ Enter) enlarges it into the layout editor over the slide: split a box into rows or columns, delete a box (its content moves to the neighbour), drag a divider (it snaps to simple ratios), choose a preset, rename or swap boxes, add, move, resize and layer floats, choose a template page's look, set the slide's options, notes and footer. A filmstrip adds, duplicates, deletes and reorders slides (drag, or Alt ↑/↓). Click a box to edit its Markdown; ? lists the keys. Done goes back to the deck, on the slide you were editing.
Every change in the layout editor rewrites only the marker lines of the text — one undo step each, no hidden layout data — so a deck shaped by clicking is still a clean text for you and your agent.
The header
One {{nyml kind: document}} block at the very top of the text is the deck's config
— and the only one. new writes carrier and a uid (the document's id; upgrade, New document and Save as new copy write one too, Save does not — a starter file has none, which is fine); once there is one, leave it as it is.
{{nyml
kind: document
carrier: slides
uid: doc-7kq2m9x4p1r8s3t5
title: Controlled Radical Polymerization
author: Yu Wang
theme: orchard
ratio: 16:9
footer: CHEM 512 · RAFT
transition: fade
slide_numbers: yes
progress: yes
section_numbers: roman
}}
| Key | Values |
|---|---|
theme | one of the 14 theme ids (below); default orchard |
ratio | 16:9 (default) or 4:3 |
footer | a line on every slide except the title page (section, outline and closing pages show it too); a slide's own <!-- @footer --> replaces it on that slide |
transition | none (default) · fade · slide · convex · concave · zoom |
slide_numbers · progress | yes (default) or no |
section_numbers | plain · roman · 01 · none (default: the theme's) |
Write each value alone after its key: a header has no comments (text after a value becomes part of it).
Also the common metadata keys (description, date, keywords,
source, license, lang, …) that the file writes into its HTML head. Unknown
keys are kept. A 0.x <!-- deck … --> block is no longer a config: it renders nothing and is
reported, and orz-slides upgrade moves it into the header.
Slides, boxes and the layout grammar
Every slide starts with a <!-- slide … --> line: an optional layout, a template page, and
options. A normal slide begins with one ## title, lifted into the slide's title band.
<!-- @name --> fills a box; text right after the title fills the layout's first box, so a
one-box slide needs no box marker. Markers count only as top-level lines: one inside a code fence
or a list is text.
| Preset | Boxes | Default ratio |
|---|---|---|
| (none) | body | — |
2col | left right | 1/1 |
3col | left mid right | 1/1/1 |
2row | top bottom | 1/1 |
main-side | main side | 2/1 |
quad | tl tr bl br | — (no ratio) |
Add a ratio after the preset, e.g. 2col 3/2 or main-side 1/2.
<!-- slide 2col 3/2 -->
## Results at a glance
<!-- @left -->
- Dispersity below **1.2** in every run
- Molecular weight grows linearly with conversion
<!-- @right -->
{{chart
type: line
labels: 10, 30, 50, 70
series: Mn = 4, 11, 19, 27
}}
<!-- @notes -->
Lead with dispersity; the linear growth is the point.
Splits of your own. One rule, applied recursively: split a box into
rows or columns; each cell is a named box or another split. Tracks are fractions
(1, 2), auto, % or px, one per item. Reach for a
preset first; a split only for nesting.
split := ("row" | "col") tracks "{" item (";" item)* "}"
item := name | split
tracks := track ("/" track)* e.g. 2/1 · auto/1 · 30%/1 · 200px/1 · 1/2/1
Reserved markers, on every slide:
| Marker | What |
|---|---|
<!-- @notes --> | speaker notes — never on the slide; in the speaker view and on Print with notes |
<!-- @footer --> | this slide's footer, replacing the header's footer |
<!-- @float left=58% top=10% w=36% h=44% --> | an overlay box over the layout (left right top bottom w h, and z= for stacking) — for a badge, a callout, a logo; use rarely |
Worked layouts
Each box mirrors the slide's grid; the text beside it is exactly what you write.
A header band over two columns
<!-- slide row auto/1 { head; col 1/1 { a; b } } -->
## Dashboard
<!-- @head -->
Full-width banner.
<!-- @a -->
Cell A
<!-- @b -->
Cell B
Three columns, the middle one split into two rows
<!-- slide col 1/1/1 { c1; row 1/1 { c2a; c2b }; c3 } -->
## Comparison
<!-- @c1 -->
Column one.
<!-- @c2a -->
Middle top.
<!-- @c2b -->
Middle bottom.
<!-- @c3 -->
Column three.
A floating takeaway over two columns
<!-- slide 2col --> ## Result <!-- @left --> Background content. <!-- @right --> More content. <!-- @float left=58% top=22% w=36% h=44% --> > **Key takeaway** sits on top of the grid.
Template pages & deck templates
Template pages are structure slides with their own design in every theme; v=N
picks a look. A layout on a template page is an error.
| Template | Write | Looks |
|---|---|---|
title | # title, ## subtitle, then a byline | v=1–6 |
section | # section title, then a line of meta; numbered automatically (section_numbers) | v=1–4 |
outline | an optional ## heading, then a list of the sections; its current item is marked automatically, or with here=N | v=1–3 |
closing | # thanks, ## questions?, contact lines; a lone {{qr https://…}} gets its own place | v=1–3 |
<!-- slide template=title v=2 --> # Controlled Radical Polymerization ## How RAFT keeps every chain growing together Yu Wang · October 2026 <!-- slide template=section --> # Methods
Deck templates start a whole deck with orz-slides new
--template: starter (the default — a tour of every kind of slide), talk (title,
outline, three sections, closing) and minimal (a title page and one slide; the file's New
document starts from it).
Per-slide options
Add these to any <!-- slide … --> marker; an unknown option is reported.
| Option | Meaning |
|---|---|
step | reveal the slide's blocks one at a time — each item of a top-level list and every other top-level block, in order across boxes |
fit=fit · fit=scroll · fit=off | shrink to fit (default) · scroll on screen, fitted on paper · no fitting, cut when too long |
bg=#0b3d2e | the slide's background: a colour or an image URL |
t=fade | this slide's transition |
class=… · id=… | a class or id on the slide |
template=… · v=N · here=N | a template page, its look, an outline's current item |
<!-- slide 2col bg=#0b3d2e t=fade step -->
A single block can be a fragment with {{attrs[.fragment]}} after it.
Fourteen themes
Each theme carries the parts only decks have — title band, title, section, outline and closing pages, slide
number, progress, footer, fragments, boxes, floats. Ten are derived from
orz-markdown's themes: Orchard orchard (the
default), Sky sky, Stationery stationery,
Preprint preprint, Small Press small-press,
Notebook notebook (a ruled exercise book), Sticker
sticker, and the dark Inscription inscription, Copper
copper and Nocturne nocturne. Four come from 0.x, updated:
Architect architect (a drafting sheet), Chalk chalk (a
chalkboard, dark), Neon neon (an instrument panel, dark) and Paper
paper (a finely printed book). The id is what the header's theme: takes;
orz-slides themes lists them. Dark themes draw charts and diagrams on dark. The orz-markdown theme
ids (light-neat-3, …) are accepted as aliases.
Fit, and how much goes on a slide
Every box shrinks its content to fit, on both axes, down to 60 %; past that the box is
clipped and marked — on the live card's badge, on the printed page, and in
orz-slides inspect --layout. Shrinking is a safety net: text at 60 % is hard to read from the back
of a room. As a guide, a 16:9 slide with a title holds unscaled in every theme about 8 bullets of
~9 words in one box, 4 of ~7 words in a 2col column, 3 short ones in
a quad cell, and a title of about 6 words on one line. Prefer two slides over one crowded one.
npx orz-slides@1 inspect talk.slides.md --layout --json # per slide and box: scale (1 = unscaled, 0.6 = the floor) and clipped
--layout renders the deck in the installed Chrome (headless; --offline blocks the
network; ORZ_SLIDES_CHROME names a Chrome when it is not found). Aim for no clipped box and no scale below about 0.85. The agent skill lists the full budgets, for 16:9
and 4:3.
Rich content in any box
Everything inside a box is orz-markdown — math, code, Mermaid diagrams, chemistry, charts, QR codes, tables, callouts, columns, tabs. Drawings render when their slide shows, at their box's size, in the theme's colours.
| Write | Get |
|---|---|
{{mermaid …}} | Mermaid flowcharts & sequence diagrams |
{{chart …}} | bar / line / pie / doughnut / radar / polarArea charts |
{{smiles …}} | chemical structures (SMILES) |
{{qr …}} | QR codes |
$…$ · $$…$$ · \ce{…} | KaTeX math and chemical equations |
{{youtube …}} · images | video embeds; images relative to the deck |
Older decks and web apps
0.x decks: inspect, then upgrade
A file or deck source made by orz-slides 0.8.5 or earlier still opens and presents as it was, but the 1.0 tools and editor work on it only after a one-time upgrade:
npx orz-slides@1 inspect old.slides.html # what it is, what upgrade changes npx orz-slides@1 upgrade old.slides.html # → 1.0 file + old.slides.md npx orz-slides@1 upgrade deck.md # a 0.x source → deck.slides.md
The <!-- deck … --> block and metadata become one header at the top, the theme the deck
showed is written explicitly (executive, poppy and sage become
sky, sticker and orchard), and a report lists every difference against
what 0.8.5 showed. Slides are now 1280 × 720, so content sized for 0.x has more room. A 0.x file's own
“Framework 1.0.0 available” offer cannot make that move — dismiss it and run
upgrade. The old deck.md stays as it was: once deck.slides.md is right,
delete it or keep it as a record (the 1.0 tools do not use it). 0.x's presentation-only Export is gone:
use Download a copy, or Print → Save as PDF.
In a web app
The editor is a component:
npm i orz-slides-browser@1, then mountEditor(element, { text, hooks }) (ES module, or
globalThis.OrzCarrier from the IIFE) — the flattened preview, the live slide card and single-slide
editing in a sandboxed frame. The layout operations are pure functions an app can run itself
(applyOp). Store the text; call assemble(text) only when a file is needed. See
docs/embedding.md.
For the full vocabulary — every header key, option, theme and capacity budget — read the agent skill (orz-slides-skills/SKILL.md) or just ask an agent.
.slides.html runs the engine inside it and anything in its content; open and edit files only from
sources you trust — a file cannot prove its own integrity (the verifier helps). The
quiet update only fetches this engine's own jsDelivr package, checks its SHA-384, and changes nothing until you
click Update now. In the editor, the deck's own scripts run only in the sandboxed preview.