The si User Manual

• Write a talk in plain Markdown; si renders animated, fluid HTML slides
• si play serves them with live reload; si build writes one self-contained HTML file per deck
• The same Markdown also makes articles (type: article), multi-page guides (a folder with a _nav.md) and labs (type: lab); si serve shows them all live
• Fluid, never fixed: slides reflow from a phone to a 4K screen — no 1280×720 canvas
• Self-contained output: CSS, JS, SVG, images and video in a single file

---
title: My Talk
theme: crdb
---

# My Talk
A subtitle under the title.

---

## A content slide
- a point
- another point

Notes: (1 min)
Order #4711 left the warehouse at 05:40 and reached the door on Thursday.

Points: Talking points
- a point to glance at
- another one

• Front matter sets title, theme, aspect, mode, and more
• --- on its own line splits slides; # is the title slide, ## a content slide

Everything is in si rules (or RULES.md) with an example for each.

Reveal content one keypress at a time:

• First this appears
• then this
• then this — each on its own press

<!-- steps -->
- First this appears
- then this

A ```stage fence generates a themed, animated flow — no external tool:

• Chains, fan-out and merges; node labels A[Label], edge labels -->|x|
• dot/flow A..B animate a route; step <node> reveals on build steps
• Full guide: docs/stage-diagrams.md

A nested list becomes a map you can fold, move and drill into:

• layout: map, right, org, radial · lines: curved, straight, orthogonal, tapered
• nodes: box, pill, underline · map-theme: auto, harbor, blueprint, ink, garden
• On a page: / searches every map, Play walks the branches; full guide: RULES.md §24
• view: 3d · camera: iso, perspective · floors: on, off: pills on a floor, linked maps hover above
• kind: blocks, bricks, toy: pills, studded bricks on a baseplate, or a cartoon island
• On a slide, steps shows one branch per click; flow: on runs dots along the lines
• si build map.md --svg --png --pdf; si mindmap import plan.opml, export --to xmind
• In the Studio, Map view: Tab adds a child, Enter a sibling, drag to move, typing renames

func send(o Order) error {
	return post(o)
}

func send(o Order) error {
	for try := 1; try <= 5; try++ {
		if post(o) == nil { return nil }
	}
	return errGaveUp
}

• window= mac, windows, terminal, none · theme= night, paper, dusk · backdrop= dusk, ocean, mint, graphite
• Same id= in a row: a show that morphs; on a slide, one click per step
• si code file.md --png --svg --gif; in the Studio, put the cursor in a block and choose Window

One inline SVG whose parts change state slide by slide:

<!-- svg: journey.svg paid -->
<!-- steps: +shipped -->
- the order ships

• Helper attributes: data-show/hide/ok/alert/flow/packets/grow/move/count
• State words in the markdown drive CSS transitions in the SVG
• Scaffold one with si new-canvas; recipe in docs/authoring-canvases.md

• Six built-ins: studio, paper, mono, crdb, acemq (brand components, embedded fonts), acemq-pro (AceMQ plus the full deck-system catalogue); si theme list prints them
• theme: my.css loads a CSS token file; theme: https://…/x.css fetches one
• si --export themes writes a gallery; si --export css-rules a starter stylesheet
• Your own CSS layers in si.user after the theme — tokens are --si-*

Open on a phone: si play --addr 0.0.0.0:7070 prints a LAN URL + QR.

Teleprompter or pen on a tablet: si play talk.md --remote keeps the deck on loopback and opens a keyed second port (play port + 1) with one QR per role: tp (the teleprompter, drives the deck) and draw (a pen pad whose strokes show on the projected slide) and clicker (a phone remote: big Next / Prev, where you are, what comes next, a stopwatch). --remote=tp picks roles, --remote-addr the address. See docs/remote.md.

The terminal drawer (`) slides up a tabbed, real shell for running commands mid-demo (docker ps, cockroach sql, …). It exists only under si play bound to a loopback address — never in a built deck, never on --addr 0.0.0.0. See docs/terminal.md.

si play <dir>              # serve with live reload (--dev: in-place hot reload)
si build <dir> --pdf       # self-contained HTML (+ PDF)
si check <dir>             # validate; exit 1 on a problem
si new <name>              # scaffold a deck (the showcase, every rule)
si new <name> --type article   # a small starter: deck, article, guide, book, site, page, lab, demo, mindmap, mindmap3d, codeshow
si publish talk.md --to linkedin   # a dry run of the post; --yes sends it (also devto, hashnode)
si code show.md --mp4      # a code show as video (si build map.md --mp4: a mind map's Play; needs ffmpeg)
si fix <dir> [--write]     # raw-HTML components (hl, pill, lockup, cards) into si syntax
si new-canvas <name>       # scaffold an animated canvas
si manual --slides         # this manual
si rules                   # the full format reference
si migrate <src>           # an AI migration prompt for an existing deck

• Post it: si publish talk.md --to linkedin turns the deck into a document post, its PDF swipeable in the feed; an article goes to LinkedIn as a link, or to dev.to or Hashnode. Always a dry run first; --yes sends.
• Get reviews: si serve . --review prints a keyed link for people on your network: they leave comments on slides and sections, and the Studio's Review panel shows them live, to reply and resolve. History in the Studio shows what changed, commits, and restores earlier versions (git).
• Film it: --mp4 on si code, on a mind map build (in 3D when the map is) and on a deck build (every slide and step, --dwell 2 for a teaser) writes video that plays anywhere, made with ffmpeg if it is installed.
• Start fast: an empty folder in the Studio opens a gallery of starters with live thumbnails, and a six-stop tour of the window.

• si rules — the complete, authoritative directive reference
• make docs-site — the rules as a browsable site, built with si itself
• docs/publish.md — LinkedIn, dev.to and Hashnode: logins, scopes, requests
• docs/stage-diagrams.md — the stage flow DSL
• docs/authoring-canvases.md — hand-authored animated canvases
• docs/timer-animations.md — the break-timer animation layer
• docs/reference/developer-reference.md — architecture and how to extend si