.slides.html

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.

You don't have to learn any of this. Start from a deck template (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
CommandWhat 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.mdturns 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 templateslist 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

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
}}
KeyValues
themeone of the 14 theme ids (below); default orchard
ratio16:9 (default) or 4:3
footera 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
transitionnone (default) · fade · slide · convex · concave · zoom
slide_numbers · progressyes (default) or no
section_numbersplain · 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.

PresetBoxesDefault ratio
(none)body—
2colleft right1/1
3colleft mid right1/1/1
2rowtop bottom1/1
main-sidemain side2/1
quadtl 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:

MarkerWhat
<!-- @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

head
a
b
<!-- 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

c1
c2a
c2b
c3
<!-- 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

left
right
float
<!-- 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.

TemplateWriteLooks
title# title, ## subtitle, then a bylinev=1–6
section# section title, then a line of meta; numbered automatically (section_numbers)v=1–4
outlinean optional ## heading, then a list of the sections; its current item is marked automatically, or with here=Nv=1–3
closing# thanks, ## questions?, contact lines; a lone {{qr https://…}} gets its own placev=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.

OptionMeaning
stepreveal 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=offshrink to fit (default) · scroll on screen, fitted on paper · no fitting, cut when too long
bg=#0b3d2ethe slide's background: a colour or an image URL
t=fadethis slide's transition
class=… · id=…a class or id on the slide
template=… · v=N · here=Na 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.

WriteGet
{{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 …}} · imagesvideo 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.

In-place Save needs a Chromium-based browser (Chrome or Edge); elsewhere, save downloads a copy. Presenting, editing (both ways), and printing work in any modern browser.
These files are programs. Opening a .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.