mdeck 2.3.0

package/docs/site/content/commands.md

@@ -0,0 +1,153 @@
+# Command guide
+
+Type these commands in a terminal. Replace `my-talk.md` with your own slide filename; in a folder that has a `slides.md` you can leave it out. If a folder or filename contains spaces, put the path in quotation marks.
+
+For how the commands, the views and the servers fit together, see [Views, commands and servers](views.html).
+
+## Everyday commands
+
+| Command | Use it to… |
+|---|---|
+| `mdeck skill --install claude` | Teach your AI assistant to write mdeck slides ([details](claude-skill.html)) |
+| `mdeck new` | Make a presentation with guided questions |
+| `mdeck run my-talk.md` | Open the launch page: present, edit, check and send from one place; slides reload when you save |
+| `mdeck edit my-talk.md` | Edit slides, colors and themes in the browser; saves to the file |
+| `mdeck themes search`, `install <pack>`, `remove`, `update`, `list` | Themes and palettes from the theme repository; see [Install or share a theme](theme-repository.html) |
+| `mdeck design [my-talk.md or folder]` | Look at themes and palettes on a sample deck and fine-tune them; saves to `extensions/` |
+| `mdeck migrate my-talk.md --dry-run` | Preview the changes needed for API 2.0 |
+| `mdeck check my-talk.md` | Check settings and look for missing local files |
+| `mdeck send my-talk.md` | Make one file to send to readers, with a PDF inside |
+| `mdeck build my-talk.md` | Make a folder to host in `dist` |
+| `mdeck pdf my-talk.md` | Make a PDF |
+| `mdeck preview` | Open the last build from the current folder |
+| `mdeck server` | Run the server for polls and for presenting from an iPad on any network ([details](audience.html#use-it-in-a-real-session)) |
+| `mdeck list`, `mdeck starter` | Look up layouts, themes and palettes |
+| `mdeck docs` | Open this documentation |
+| `mdeck --help` | Show a short list of commands |
+
+## The launch page
+
+`mdeck run my-talk.md` opens a page on your own computer with everything for this talk. It is what the preview's plain address, such as `http://localhost:5173/`, shows; the slides themselves are at `?view=deck`.
+
+- **Preview:** a small live copy of the deck to flip through; click it to open the audience window at that slide.
+- **Present:** the presenter view, audience window and reader view, each in a new tab. The presenter view has notes, drawing controls, a timer and next-slide preview; switch to its slide-only layout for a single screen. The audience window shows slides without notes. Fullscreen is a control inside either view, not a separate view.
+- **Write and learn:** the visual editor and these guides. Each starts the first time you click it.
+- **Send:** buttons that make the `dist` folder, one file to send, or a PDF, next to your slide file, and show them in your file manager.
+- **Polls:** for a deck with polls: the server (built in, or the `server` setting and whether it answers), the join link and session code for phones, and for a server of your own the key that lets your browser move the phones along and reset polls (see below).
+- **Check:** the same problems `mdeck check` reports, such as missing pictures.
+
+The key is the one the server was started with. Start `mdeck run` with the same key, for example `MDECK_SERVER_KEY=choose-a-secret mdeck run my-talk.md`, and the launch page shows it, and its presenter and audience buttons open those views with it, so they move the phones along. Local views control this deck through the laptop; paired devices receive only a revocable token. Pairing codes never contain the master key. A hosted presenter can unlock the server separately with `?serverkey=…`; that key is removed from the address as soon as the page has it. It never goes into the slide file, because that file reaches everyone who opens the slides.
+
+Two options make the slides reachable from other devices:
+
+| Option | What it does |
+|---|---|
+| `--network` | Phones and tablets on the same network can open the slides. |
+| `--server` | An iPad on any network can present through your own server. It takes the server's address, or finds it in the deck's `server` setting or in the `MDECK_SERVER` variable, in that order. The key goes in `MDECK_SERVER_KEY`. |
+
+See [Draw on your slides](drawing.html#present-from-an-ipad) for both. The launch page itself and its buttons only work on your own computer. `--port 4000` chooses the port and `--no-open` starts without opening a browser.
+
+## Open a particular guide
+
+```sh
+mdeck docs getting-started
+mdeck docs sharing
+```
+
+Use the page name from its address, without `.html`. The welcome page is `index`.
+
+`mdeck docs --no-open` starts the documentation server without opening a browser. `mdeck docs --port 4200` chooses a port number. If the usual port is busy, mdeck tries another one.
+
+To make a static copy of the documentation site, use `mdeck docs --build`. This saves it in `docs/site/dist` inside the mdeck project, separately from your presentation builds.
+
+## Edit in the browser
+
+```sh
+mdeck edit my-talk.md
+mdeck edit my-talk.md --no-open
+mdeck edit my-talk.md --port 4300
+```
+
+The editor opens in your browser and writes every change into the slide file. `--no-open` starts it without opening a browser window; `--port` chooses the port. See [Edit slides in your browser](editing.html).
+
+## Design themes and palettes
+
+```sh
+mdeck design my-talk.md
+mdeck design                 # in a folder without a deck
+mdeck design brand/
+```
+
+The design page shows themes and palettes on a sample deck with every kind of slide, light and dark, and lets you copy a built-in one and fine-tune its colours, fonts, sizes and spacing. With a slide file, it saves into the `extensions` folder beside it and can put the result in the deck. With a folder, or nothing, it saves into that folder's `extensions`, where any deck kept there finds them; no slide file is needed. `--no-open` and `--port` work as for `mdeck edit`.
+
+## Output options
+
+| Command | Result |
+|---|---|
+| `mdeck build my-talk.md` | A folder in `dist` with every view, to host or copy |
+| `mdeck build my-talk.md --reader` | A hosted reader folder with speaker notes removed; add `--notes` to retain them |
+| `mdeck build my-talk.md -o talk.html` | Choose the output filename; local media stays alongside it |
+| `mdeck build my-talk.md --single-file -o talk.html` | Embed local images and media in one HTML file of the presentation |
+| `mdeck build my-talk.md --launchers` | Include presenter launchers in the folder build |
+| `mdeck send my-talk.md` | One file for readers: the reader view, speaker notes removed, a PDF inside |
+| `mdeck send my-talk.md --notes` | The same, keeping the speaker notes |
+| `mdeck send my-talk.md --no-pdf` | The same, without rendering the PDF |
+| `mdeck pdf my-talk.md -o talk.pdf` | Render the slides to a PDF file |
+| `--no-drawings` | Leave out the drawings from `my-talk.drawings.json`, for `build`, `send` and `pdf` |
+
+See [Send, host or print your slides](sharing.html) for help choosing between them. Unknown options, missing option values and extra filenames stop the command before it changes any output. `--output=path` and `-o path` are both accepted. `mdeck preview --no-open --port 4200` previews without opening a browser and chooses a port.
+
+## Update a deck to API 2.0
+
+```sh
+mdeck migrate my-talk.md --dry-run
+mdeck migrate my-talk.md
+```
+
+The dry run lists changes without writing files. Applying them renames deck settings, changes local extension manifests from `template` to `layout`, updates `mdeck/template-api` imports in local extensions and components, and renames `<deck>.ink.json` to `<deck>.drawings.json`. Unrelated source text and comments stay unchanged. Speaker notes use `:::notes` blocks; there is no migration for metadata notes.
+
+Conflicting old and new values, or two drawings files, stop the whole migration before any writes. Originals are copied into `.mdeck-backups/migration-…` beside the deck. Running it again makes no changes. Shared component folders outside the deck are not rewritten; update those imports separately.
+
+## Check more strictly
+
+```sh
+mdeck check my-talk.md --strict
+```
+
+The ordinary check fails when it finds an error. The strict check also fails when it finds a warning, such as a layout name it does not recognize.
+
+The check does not measure whether text fits on the slide. Always look through the preview too.
+
+## Layouts, themes and palettes
+
+```sh
+mdeck list layouts my-talk.md
+mdeck starter comparison my-talk.md
+```
+
+The first lists the layouts available to your talk. The second prints starting text for one layout. `mdeck list layouts --json` prints the layout descriptions in a structured form intended for other tools.
+
+```sh
+mdeck list my-talk.md
+mdeck list themes my-talk.md
+```
+
+The first lists every layout, theme and color palette your talk can use, including any kept in an `extensions` folder beside it. The second lists only themes; `palettes` works the same way. `--json` prints the same information for other tools. The complete registry has `schema: 2` and `layouts`, `themes`, `palettes` and `warnings` fields. A filtered listing such as `list layouts --json` is a map keyed by layout ID. Extension TOML manifests still use `schema = 1`.
+
+## Slides from an AI assistant
+
+```sh
+mdeck skill
+mdeck skill --install claude codex
+mdeck skill --print
+```
+
+Installs the slide-writing skill for the assistants you use, or prints it for any other tool. See [Work with an AI assistant](claude-skill.html).
+
+## Why do some examples use Node directly?
+
+`mdeck` is the normal command. After the one-time `npm link` setup, you can use it from any folder.
+
+`node bin/mdeck.js` runs the same program directly from its project folder. It is useful when working on mdeck itself, but it is not a replacement you need to learn for everyday use.
+
+From the project folder, `npm start -- my-talk.md` runs `mdeck run`, and `npm run build -- my-talk.md` builds. These use the same program.

package/docs/site/content/components.md

@@ -0,0 +1,134 @@
+# Create interactive content
+
+A component is a small piece of JavaScript that puts something interactive on a slide: a chart with sliders, a quiz, a calculator. You do not need one for ordinary presentations, and you do not need to write one yourself. Describe it to your assistant:
+
+```prompt
+Make a component that shows a titration curve, with a slider for the
+added volume, and put it on the slide about equivalence points.
+```
+
+This guide describes the files it writes, for review or for writing them by hand.
+
+## Add a deck-local component
+
+Create a `components` folder beside the deck's Markdown file. A file named `Greeting.jsx` is registered as the lowercase tag `<greeting>`:
+
+```jsx
+import { h } from 'preact'
+import { useState } from 'preact/hooks'
+
+export default function Greeting({ name = 'everyone' }) {
+  const [visible, setVisible] = useState(false)
+  return <div>
+    <button onClick={() => setVisible(!visible)}>Show greeting</button>
+    {visible && <p>Hello, {name}!</p>}
+  </div>
+}
+```
+
+Use it in an ordinary slide or a named region:
+
+```html
+<greeting name="garden team" />
+```
+
+The default export must be a Preact component. Deck-local discovery supports `.jsx` files. Import hooks from `preact/hooks`; the build resolves Preact to the framework's instance.
+
+## Share components between decks
+
+To use the same components in several decks, keep them in one folder and list it in each deck's settings:
+
+```yaml
+---
+theme: neue
+components:
+  - ../shared-components
+  - ~/mdeck-components
+---
+```
+
+Paths are relative to the deck's Markdown file; `~/` starts in your home folder. Every `.jsx` file in a listed folder becomes a tag, just like the deck's own `components` folder. Helper files in subfolders can be imported from those components.
+
+When two folders have a component with the same name, the deck's own `components` folder wins, then the listed folders in their order, then mdeck's built-in components. Edits to a shared component reload every deck that is open in `mdeck run`. `mdeck check` reports a listed folder that does not exist.
+
+Builds contain the component code, so a built presentation does not need the shared folder. Someone who gets your slide file to work on needs that folder too.
+
+## How content reaches a component
+
+HTML attributes arrive as string props. Text between the opening and closing tags arrives as the `children` string. The HTML-to-component bridge uses `textContent`; it does not pass a nested JSX tree.
+
+Deck-local names override built-in component names. Avoid a collision unless you intend to replace that component for the whole deck.
+
+## Assets and dependencies
+
+Import assets from JSX so Vite can include them in builds. Install extra dependencies beside the deck, or in the framework checkout. Local component code is included only in decks that discover it.
+
+Slides stay mounted while navigating. For media or ongoing work, listen to the `slidechange` event on `document.querySelector('deck-stage')` and check whether `event.detail.slide` contains your component. Clean up listeners when the component unmounts.
+
+## Audience interaction
+
+Components can collect answers from phones. An activity has two halves:
+
+- **On the slide**, the component itself shows the answers. `useRoom` from `mdeck/live` follows its room on the server and receives every answer live.
+- **On the phones**, the server's answer page shows a form. The component describes that form with a static `phone` function; mdeck calls it for the activity on the presenter's current slide and sends the result to the phones.
+
+The phones never load the deck, so the form is a description, not code. Three kinds are available:
+
+| `type` | Shows | Other fields | An answer's `value` |
+|---|---|---|---|
+| `choice` | One button per option; the latest tap counts | `options` (list of text) | The chosen option |
+| `text` | A text box and a send button; any number of answers | `placeholder`, `maxLength` (default 200) | The text |
+| `scale` | A row of numbers | `min` (default 1), `max` (default 5), `minLabel`, `maxLabel` | The number |
+
+Each takes a `question`. A word collector:
+
+```jsx
+import { h } from 'preact'
+import { useRoom, QrCode } from 'mdeck/live'
+
+export default function Words({ room }) {
+  const { messages, joinUrl, localJoinUrl } = useRoom(room)
+  return <div>
+    <p>{messages.map(m => m.data.value).join(' · ')}</p>
+    {joinUrl ? <QrCode url={joinUrl} size="280" /> : <a href={localJoinUrl}>Try the answer page</a>}
+  </div>
+}
+
+// What the phones show while this slide is on screen.
+Words.phone = ({ question }, { slideTitle }) => ({ type: 'text', question: question || slideTitle, placeholder: 'One word' })
+```
+
+`phone(props, { slideTitle })` receives the tag's attributes and the slide's heading. A component without `phone` still shows answers on the slide, but the phones keep waiting while it is on screen. Only the current slide's rooms stay connected, so a deck can hold many activities.
+
+`useRoom(room)` returns:
+
+| Value | Meaning |
+|---|---|
+| `messages` | Every answer so far, oldest first: `{ n, at, from, data: { value } }` |
+| `joinUrl` | The deck's join link for the QR code, or `null` when phones cannot reach the server |
+| `localJoinUrl` | The answer page on this computer, for trying it out |
+| `code` | The deck's session code |
+| `canReset`, `reset()` | Whether this browser may clear the room, and doing it |
+| `connected` | Whether the live connection is open |
+
+`QrCode` draws the code. `latestByDevice(messages)`, also from `mdeck/live`, keeps each device's latest answer, for answers people may change. Where the server runs is described in [Ask your audience](audience.html).
+
+## Print, PDF and Read mode
+
+In a PDF, and in the reader's Read mode, every slide is shown at once and none of them is the active slide. There, mdeck reveals every step and places the slide inside an element with the `data-deck-static` attribute. A component that builds up step by step, or waits for its slide, should then show its finished state. Printing can start while the deck is open, so also listen for the stage's `printchange` event:
+
+```jsx
+useEffect(() => {
+  const stage = document.querySelector('deck-stage')
+  const sync = () => setFinished(!!ref.current.closest('[data-deck-static]'))
+  sync()
+  stage?.addEventListener('printchange', sync)
+  return () => stage?.removeEventListener('printchange', sync)
+}, [])
+```
+
+Transitions are turned off in print, so the finished state appears immediately. After printing, the stage puts each slide back to the step it was on.
+
+## When to use a layout instead
+
+A component is a piece of a slide, such as an activity or visualization. A [layout](custom-layouts.html) arranges an entire slide and declares the areas and settings authors can fill in.

package/docs/site/content/drawing.md

@@ -0,0 +1,72 @@
+# Draw on your slides
+
+You can draw on a slide while you present, or ahead of time: circle a number, underline a line of code, sketch an arrow. It works with a mouse, a finger, and best with an iPad and its pencil. What you draw is kept with the presentation and shows again the next time you present it, in the reader view and in PDFs.
+
+## Start drawing
+
+Press **D** in standalone slides or in the presenter view, or use the pen button (**Draw** in the presenter view). A toolbar appears on the slide:
+
+| Tool | What it does |
+|---|---|
+| Pen | Thin to thick with the pencil's pressure. Kept. |
+| Highlighter | A wide, see-through stroke in its own colours, always below the pen's strokes. Kept. |
+| Select and move | Draw a loop around strokes, or tap one, to select it; a finger's tap on a stroke selects it with any tool. Drag inside the dashed box with the pen to move it; a straight line shows handles at its ends, which the pen moves. **Delete** (or the toolbar's bin) removes the selection. |
+| Laser pointer | A red dot with a white core and a short trail that disappears by itself, for pointing at something. With a pencil that can hover, the dot follows it without touching. Never kept. |
+| Eraser | Removes whole strokes you touch. |
+
+**Zoom**: two fingers zoom into the slide and move around it, one finger moves a zoomed slide, and Ctrl + scroll (a trackpad pinch) zooms on a laptop. Only the slide grows; the bars and the toolbar keep their size. The audience window shows the same part of the slide. **1:1** at the top left shows the whole slide again, as does the next slide.
+
+On a touch screen such as an iPad, drawing is on as soon as the presenter view opens, and in the deck as soon as the pencil touches it, with the toolbar folded into its button in the bottom right corner (↘ folds it again). Until then, a tap on the right third of the screen goes forward, on the left third back, and a swipe does the same. Drawing starts with the laser pointer; choose the pen or the highlighter to write. The pen and the highlighter each have colours and three sizes, and each keeps its own; one pen colour is **Accent**, the accent colour of the theme and palette: a drawing in it changes with them. The other pen colours follow light and dark: on dark slides red, blue and green are lighter, and the text colour is white instead of black. The toolbar also has undo and redo (also Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z), **Clear this slide**, and **×** to stop drawing; **D** and **Escape** do the same. While you draw, the pencil and the mouse draw; fingers keep working: a swipe to the left goes forward, to the right back, a tap on a stroke selects it, and buttons and polls on the slide still respond. Turn slides with the arrow keys or the presenter view's arrows, as always. Holding the pen still for half a second at the end of a stroke makes it a straight line.
+
+**I** hides and shows what was drawn before, for example when a slide should look clean again. The toolbar has the same switch.
+
+The audience window, and any other deck window in the same browser, shows every stroke as you draw it.
+
+## Where drawings are kept
+
+Drawings live in a file next to your slides: `my-talk.drawings.json` for `my-talk.md`. Keep the two together, and send or check in both.
+
+- **With `mdeck run`**, each stroke is saved in that file as soon as you lift the pen. Nothing reloads, and the talk goes on.
+- A slide that gets its first drawing receives an `id:` in its settings, made from its heading, for example `id: the-important-part`. The drawing stays with that slide when you add or move slides. If you change the `id:` in the editor, the drawing moves with it.
+- If you delete a slide that has drawings, they stay in the file. `mdeck check` tells you about them; bring the slide back, or delete them from the file.
+- The first save of a session keeps a copy of the previous file in `.mdeck-backups`, next to your slides.
+- **Opened from a built folder or a single file**, the page has nowhere to save. Drawings are kept in that browser, and the toolbar's download button saves them as the drawings file, to put next to your slides. Safari may clear such browser data after a week without use, so download it after drawing.
+
+Builds and PDFs include the drawings. To leave them out, add `--no-drawings`:
+
+```sh
+mdeck pdf my-talk.md --no-drawings
+```
+
+## Present from an iPad
+
+There are two ways.
+
+**The iPad on its own.** Connect it to the projector, which usually shows the same picture as the iPad, and open standalone slides with **Present** from the reader view. Swipe left or right to go forward or back, also while drawing. This keeps notes off the wall.
+
+**The iPad next to your laptop.** The laptop shows the slides on the projector; you draw and go through the slides on the iPad, with your notes on it.
+
+1. Start `mdeck run my-talk.md --network`, so the iPad in the same network can reach your laptop.
+2. On the launch page, under **Present from an iPad**, choose **Show pairing code** and scan it with the iPad's camera. The presenter view opens on the iPad, paired with your laptop, so it may save drawings and steer the phones of a poll. It is the same presenter view as on the laptop; pairing only gives it these rights. Once it is open, the launch page says so.
+3. On the laptop, open the **audience window** from the same place and move it to the projector. It follows the iPad: slides, revealed points, and drawings as you draw them. Navigation in the audience window also updates the iPad's slide, notes and next-slide preview.
+
+A pairing code works once, for ten minutes. **Unpair** on the launch page ends every pairing; so does stopping `mdeck run`. Scan a new code afterwards.
+
+**The iPad on another network.** Some networks, often big Wi-Fi networks at universities, do not let devices reach each other, and a laptop's firewall may not let the iPad in. With a server of your own (see [Ask your audience](audience.html#use-it-in-a-real-session)) the iPad does not need to reach your laptop at all: your laptop connects out to the server, and the server passes the iPad's requests to it. The slides are not uploaded or stored anywhere.
+
+1. Tell mdeck where your server is: `server: https://rooms.example.org` in the deck's settings, or `MDECK_SERVER` in your shell, or the address after the option in the next step.
+2. Start `MDECK_SERVER_KEY=your-key mdeck run my-talk.md --server`. The key is the one the server was started with.
+3. On the launch page, choose **Show pairing code** under **Present from an iPad** and scan it. The address in the code is on your server and contains a long random name, so treat it like a private link.
+4. Open the **audience window** on the laptop as before. It follows the iPad through the server.
+
+Everything else works as with `--network`: drawings are saved in the drawings file beside the deck, and the iPad may steer polls. Editing the slides on the laptop reloads the iPad too. The server only passes on what the presenter and audience pages need; the launch page, the editor and the other files in your folder are not reachable through it. Stopping `mdeck run` ends the connection, and a pairing code stops working when you unpair or stop.
+
+On a touch screen the presenter view shows only the slide, with a small bar at the top: timer, previous and next, draw, **Notes** (a drawer with your notes and the next slide, also **N**), full screen, and a button back to the layout with notes beside the slide. Your choice is remembered on that device.
+
+With a server of your own (the `server` setting, see [Ask your audience](audience.html)), the same also works with a hosted deck: open the presenter view on the iPad with your key (`?serverkey=…`), and the audience window anywhere else follows it. With the deck opened through `mdeck run` and the server's key set (`MDECK_SERVER_KEY`), the paired iPad and the audience window talk over your own network, and only the polls go through the server. Drawings are then kept on the iPad; download the drawings file after the talk.
+
+## Tips for the iPad
+
+- **Full screen**: the full-screen button (four corners) or **F**, where the browser allows it. Safari on an iPhone does not. Alternatively, use Share → **Add to Home Screen**: the deck then opens without Safari's bars. Such a Home Screen app keeps its own browser data, apart from Safari's.
+- **Fingers and the pencil**: the pencil draws, fingers operate the slides, also while drawing. Swipe left to go forward, right to go back; tap a stroke to select it. To draw with a finger (on a device without a pencil), switch on the hand button on the toolbar; fingers then draw instead.
+- **Networks**: many large Wi-Fi networks do not let devices reach each other. If the iPad cannot open the pairing code, connect both to a phone hotspot.

package/docs/site/content/editing.md

@@ -0,0 +1,59 @@
+# Edit slides in your browser
+
+Your assistant and any text editor write the same slide file. If you prefer clicking and typing in forms, mdeck also has a visual editor:
+
+```sh
+mdeck edit my-talk.md
+```
+
+This opens a page on your own computer with three parts:
+
+- **Slides**, on the left: the list of slides. Select one, add a new one from a list of layouts, duplicate it, remove it, or move it up and down.
+- **Preview**, in the middle: your presentation, always showing the selected slide. Use the buttons underneath to step through points and slides.
+- **Details**, on the right: what the selected slide contains. Every layout has one or more text areas for its content, and some have settings such as a picture or the width of two columns. Speaker notes and the slide's name are here too. The **Markdown** tab shows the same slide as plain text, if you prefer that.
+
+The **Deck** tab in the right panel changes the whole presentation: the theme (chosen from pictures of your first slide in each one), the colors, light or dark, your name and title, and the slide shape.
+
+It is not a drag-and-drop editor like PowerPoint or Keynote. You do not place boxes or resize text on the slide; you fill in each slide's content and settings, and the layout and theme decide where things go and how they look. That is what keeps every slide consistent, and what lets you change the whole look with one setting.
+
+## Changes are saved as you go
+
+There is no save button. Every change is written into your slide file within a moment; the status next to the file name says *Saved* when it is done. Undo and redo (⌘Z and ⇧⌘Z, or Ctrl on Windows and Linux) work across everything you change, and the file follows along.
+
+Because the file is the only copy, you can keep your text editor or your AI assistant working at the same time. When either changes the file, the visual editor shows the change. If both change the same file at the same moment, the editor asks which version to keep.
+
+The editor only ever rewrites the parts of the file you change. Your blank lines, comments and the order of everything else stay as they are.
+
+Before the first change of each editing session, mdeck copies the file as it was into a `.mdeck-backups` folder beside it, named after the deck and the time, for example `.mdeck-backups/my-talk-2026-09-29T10-15-00Z.md`. It keeps the ten newest copies of each deck. If you keep your slides in Git, add `.mdeck-backups/` to your `.gitignore`.
+
+## Look at and fine-tune themes and palettes
+
+**Design themes**, at the top, opens the design page in a tab of its own. You can also start it on its own with `mdeck design my-talk.md`, or with `mdeck design` in a folder that has no deck yet. Themes and palettes are saved in an `extensions` folder next to your slide file (or in that folder), so they travel with the talk.
+
+The usual way to get a new look is to describe it to your assistant; see [Create a theme or palette](theme-authoring.html). The design page is where you look at the result and adjust it:
+
+- A **theme** is a whole look. The form has its fonts, sizes, spacing and the palettes it offers; the rules that arrange each slide are CSS under *Advanced*.
+- A **palette** is a set of colors, light and dark. Pick a color for each role and see the preview repaint at once.
+
+The preview shows a **sample deck** with one slide of every kind: title, chapter, lists and code, a table, callouts, lecture blocks, two columns, a statement, pictures. Step through it to see how a change looks everywhere. **My deck** shows your own slides instead. Above the preview you choose the palette a theme is shown with, the theme a palette is shown in, and light or dark; this only changes the preview.
+
+On the left, your own themes and palettes come first. Below them are the ones that come with mdeck; these cannot be changed in place. Choose one and press **Copy to customise** to start from it under a new name. A new palette can also start from plain colours.
+
+From the editor, **Customise theme** or **Customise palette** in the **Deck** tab opens the design page with a copy of the one your deck uses. **Use in my deck** puts a theme or palette in your slide file, and the editor shows it straight away.
+
+Slide layouts are small programs; ask your assistant for one, or see [Make your own layouts](custom-layouts.html).
+
+## Keyboard shortcuts
+
+| Keys | What happens |
+|---|---|
+| ⌘Z, ⇧⌘Z | Undo, redo |
+| ↑ ↓ | Select the previous or next slide (outside text fields) |
+| ⌘↩ | Add a slide after the selected one |
+| ⌘⌫ | Remove the selected slide |
+
+## Good to know
+
+- `mdeck edit` runs only on your computer. It is not a website other people can open.
+- The editor checks your slides the same way `mdeck check` does and shows problems next to the slide they belong to.
+- To present, use the **Present** button at the top right, or open the presenter view from the launch page of `mdeck run my-talk.md`.

package/docs/site/content/getting-started.md

@@ -0,0 +1,103 @@
+# Make your first presentation
+
+You will install mdeck, teach your AI assistant how to write mdeck slides, give it material you already have, and open the deck it makes. If mdeck is already installed, skip to “Teach your assistant about mdeck.”
+
+## Set up mdeck once
+
+mdeck needs Node.js and npm on your computer. Install [Node.js](https://nodejs.org) (version 22 or newer); npm comes with it.
+
+Open a terminal. A terminal is an app where you type short commands: Terminal on macOS, or PowerShell on Windows. A text editor may also have a Terminal menu.
+
+Run this command to install mdeck:
+
+```sh
+npm install -g mdeck
+```
+
+You normally do this only once. To update later, run it again.
+
+Check that the command is ready:
+
+```sh
+mdeck --help
+```
+
+If your computer does not recognize `npm` or `mdeck`, see [When something goes wrong](troubleshooting.html#the-command-is-not-recognized).
+
+## Teach your assistant about mdeck
+
+mdeck comes with a set of instructions, called a *skill*, that tells an AI assistant how mdeck slides are written, which layouts and looks exist, and how to check its work. Install it for the assistant you use:
+
+```sh
+mdeck skill --install claude
+```
+
+Replace `claude` with `codex`, `cursor`, `copilot` or `gemini` for those tools. Run `mdeck skill` to see the list. For Cursor, Copilot and Gemini, run it in your talk's folder.
+
+## Hand over your material
+
+Make a folder for your talk and copy in what you have: old slides, a PDF, a Word document, photos, or rough notes. Open your assistant in that folder and tell it what to make from them, for whom, and how long:
+
+```prompt
+/write-slides Make a 10-minute talk for our team from report.docx and
+the photos in img/. It is about what we learned from the spring
+garden project. Keep my three main points, in English.
+```
+
+In other assistants than Claude Code and Gemini CLI, simply ask for an mdeck presentation. The assistant writes a deck such as `spring-garden.md` from your files, checks it, and tells you what to do next.
+
+No material yet? Describing the talk works too; the assistant then drafts the content as well, and you have more to check.
+
+## Open the preview
+
+In a terminal opened in your talk's folder, run:
+
+```sh
+mdeck run spring-garden.md
+```
+
+Your browser opens the launch page for your talk. Click **Audience window** to see just the slides, or **Presenter view** for notes, drawing controls and a timer. Press the right arrow key to move to the next slide, and the left arrow key to go back. Press **F** to go fullscreen.
+
+Keep the terminal open while working. If the browser does not open, click or copy the launch page address shown in the terminal. It usually is `http://localhost:5173/`. The [command guide](commands.html#the-launch-page) describes everything else on the launch page.
+
+## Make it yours
+
+Read through every slide and its notes, next to your original material. Check that nothing important was dropped and nothing was added that you did not say. Then tell the assistant what to change:
+
+```prompt
+Slide 3 is too dense; split it in two. You left out the part about
+the tomato beds from page 4 of the report. Make the closing slide a
+big statement.
+```
+
+The preview reloads each time the file changes. Small things, such as a word or a number, are often quicker to change yourself: open the `.md` file in any text editor and save. [Read and adjust your slides](writing.html) explains what you will see in the file.
+
+That is the everyday workflow: ask, look at the preview, adjust. When you are finished, press `Ctrl+C` in the terminal to stop it.
+
+## Prefer to start without an assistant?
+
+Run:
+
+```sh
+mdeck new
+```
+
+mdeck asks for a file name, a theme, colors, and some starting slide layouts. Press Enter to accept a suggested answer. Replace the example words in the new file with your own. The starter may mention a logo image. Add that image, or remove the `logo:` line if you do not want a logo.
+
+Or make the file yourself: save a new plain-text file called `my-talk.md` (not `my-talk.md.txt`), paste this in, and run `mdeck run my-talk.md`:
+
+```markdown
+# My first presentation
+
+Hello, everyone!
+
+---
+
+# Three things to remember
+
+- Start with one idea.
+- Show a helpful example.
+- Leave time for questions.
+```
+
+Next, learn [how to work with your assistant](claude-skill.html) or [choose a layout](layouts.html).

package/docs/site/content/layouts.md

@@ -0,0 +1,126 @@
+# Choose a slide layout
+
+A layout arranges your words and pictures. Your assistant chooses one for each slide; this page shows what each looks like in the file, so you know what to ask for:
+
+```prompt
+Make slide 2 a title slide, and put the photo of the garden beside
+the text on slide 5.
+```
+
+To change a layout by hand, copy one of the examples below and replace the example text with your own.
+
+<!-- preview -->
+
+## A title and subtitle
+
+Use `title` at the beginning of a talk. The `#` line is the title; the `##` line is its subtitle.
+
+```markdown
+:::meta
+layout: title
+:::
+# A small idea
+## A clear presentation
+```
+
+## A normal content slide
+
+Leave out the layout setting for a heading with ordinary content underneath:
+
+```markdown
+# What we learned
+
+- Make room for questions.
+- Use examples people recognize.
+- End with a next step.
+```
+
+## A big statement or quote
+
+Use `focus` for a short message. The optional `attribution` names the person who said it.
+
+```markdown
+:::meta
+layout: focus
+attribution: "Our team"
+:::
+# Good questions make better conversations.
+```
+
+## A new section
+
+Use `chapter` between the main parts of a longer talk:
+
+```markdown
+:::meta
+layout: chapter
+number: 2
+part: "What we learned"
+:::
+# Listen first
+
+Three lessons from our conversations.
+```
+
+The `part` name also becomes the section label on following slides. Set `section:` on a later slide to change it.
+
+## A picture beside your words
+
+Use `image-text` and tell mdeck where the picture is saved:
+
+```markdown
+:::meta
+layout: image-text
+image: ./img/garden.jpg
+alt: "A community garden in spring"
+:::
+# A place to grow
+
+Our neighbors turned an empty space into a garden.
+```
+
+Replace the image path with your own. The [picture guide](pictures-and-video.html) explains how paths work.
+
+## Two areas side by side
+
+Use `split` and name the content for each side. A **slot** is simply a named area on the slide.
+
+```markdown
+:::meta
+layout: split
+props:
+  ratio: [1, 2]
+:::
+# Two ways to begin
+
+:::slot left
+## Ask
+What do people need?
+:::
+
+:::slot right
+## Listen
+Make space for their answers before suggesting a solution.
+:::
+```
+
+`ratio: [1, 2]` makes the right side twice as wide as the left. Use `[1, 1]` for equal widths. The heading above the slots is shared by both sides.
+
+Some older examples do not name the sides. In those slides, mdeck puts the first piece of content on the left and the rest on the right.
+
+## A picture that fills the slide
+
+Use `full-bleed-image` for a large photograph. `overlay: true` adds the theme's overlay treatment to help the title stand out.
+
+```markdown
+:::meta
+layout: full-bleed-image
+image: ./img/garden.jpg
+overlay: true
+:::
+# Small beginnings
+```
+
+## More layouts
+
+Your presentation folder can contain extra layouts made for your team or organization. Learn how to [use a reusable layout](reusable-layouts.html). If none of them fits, your assistant can make a new one for the talk, just by describing it.