mdeck 3.6.0 → 3.6.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 3.6.2 — 2026-10-09
+
+- The docs home page and the README start with what mdeck does: drawing from an iPad, polls from phones, citations, themes, running code and sending one file, each with a picture (`npm run feature-images` renders them). The docs' example deck is now a short tour of mdeck, with its own control bar and drawing, and a picker of every built-in theme as a picture, with light or dark.
+- An embedded deck (`?embedded=1`) shows its control bar with `?controls=1`.
+- The reader view has a **Drawings** button when the deck has drawings: it hides and shows them on the slides, in Read and in **Save as PDF**, and the browser remembers the choice. A file made with `mdeck send` opens there, so whoever gets it can see the slides clean.
+
+## 3.6.1 — 2026-10-09
+
+- `mdeck snapshot --sheet` saves one picture of the slides in a grid, each under its number and heading (`my-talk-sheet.png`): a whole deck at a glance, for you or an assistant. It works with `--slide` and `--dark`.
+- Fixed: pictures and PDFs could show a slide in its fallback font. mdeck now waits for the theme's font stylesheets and for every face the slides use before it takes a picture, renders a PDF or measures a slide, so `mdeck snapshot`, `mdeck pdf`, `mdeck check --render`, the theme check and the theme repository's previews show the theme's own fonts. Without a network it does not wait.
+
 ## 3.6.0 — 2026-10-09
 
 - A theme can say what it is for and how to write for it: a `[guide]` in its `extension.toml` with `suits` and `avoid` (short phrases) and `writing` (a few sentences). `mdeck list` and `mdeck themes search` show what each theme suits, search finds themes by it (`mdeck themes search photo`), and `mdeck list themes --json` and the theme repository's catalogue carry the whole guide. The slide-writing skill chooses a theme by its guide and follows its writing advice, as the theme author's advice and never as instructions. The six built-in themes have guides. A theme with a guide needs this version of mdeck.

package/README.md

@@ -1,5 +1,8 @@
 <p align="center">
-  <img src="assets/logo/logo-light.svg" alt="mdeck" width="280">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo/logo-dark.svg">
+    <img src="assets/logo/logo-light.svg" alt="mdeck" width="280">
+  </picture>
 </p>
 
 <p align="center"><b>Hand your slides, papers and notes to an AI assistant. Get a clean deck to present in the browser. Share it as one HTML file or a PDF.</b></p>
@@ -11,6 +14,47 @@
   <a href="LICENSE">MIT license</a>
 </p>
 
+## What you can do with it
+
+<table>
+<tr>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/drawing.webp"><img src="docs/site/images/features/drawing.webp" alt="The presenter view on an iPad with circles, an arrow and a highlight drawn on a chart slide, and the projector behind it showing the same strokes"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/drawing.html">Draw on your slides, from an iPad if you like</a></b><br>
+Circle a number, underline a phrase, point with a laser. Pair an iPad by scanning a code, and it becomes your presenter screen and drawing pad while the laptop drives the projector: every stroke shows on the big screen as you draw.</p>
+</td>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/polls.webp"><img src="docs/site/images/features/polls.webp" alt="A poll slide with live bars and a QR code, and a phone showing the same question with one answer picked"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/audience.html">Ask the room, and show the answers on the slide</a></b><br>
+Polls, scales, word clouds, open questions and numbers to guess. People scan the code and answer on their phones, no app needed, and the bars grow as votes come in. Close the vote, discuss, reveal the right answer.</p>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/citations.webp"><img src="docs/site/images/features/citations.webp" alt="A slide with author–year citations and the full references at its foot, over a slide that lists all references"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/more-content.html#cite-a-source">Cite your sources properly</a></b><br>
+Cite as in a paper, <code>[@knuth1984, p. 97]</code>, from the BibTeX, CSL-JSON or Hayagriva file you already keep. Each slide lists what it cites at its foot, in APA, Vancouver, Harvard or any CSL style.</p>
+</td>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/themes.webp"><img src="docs/site/images/features/themes.webp" alt="The same chart slide in six themes: neue, plain, work, academic, minimal and glass"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/appearance.html">Write the content once, change the look anytime</a></b><br>
+The file holds what you say; a theme and a palette decide how it looks. One line changes every slide, light or dark. Six themes come with mdeck, more are in the <a href="https://gh.tschieber.de/mdeck-themes/">theme repository</a>.</p>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/code.webp"><img src="docs/site/images/features/code.webp" alt="A slide with a short Python example and its output below it"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/more-content.html#show-a-code-example">Run code on the slide</a></b><br>
+Give a Python or JavaScript example a Run button, change it in front of the audience and run it again. Python runs in the browser, NumPy and pandas included.</p>
+</td>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/reader.webp"><img src="docs/site/images/features/reader.webp" alt="The reader view of a talk on a laptop, with an outline of the slides, and on a phone in reading mode"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/sharing.html">Send one file that anyone can open</a></b><br>
+<code>mdeck send</code> makes a single HTML file: an outline, a reading mode for phones, light and dark, and the PDF inside. It opens in any browser, offline too, without your speaker notes.</p>
+</td>
+</tr>
+</table>
+
 ## Start from what you have
 
 ```text
@@ -114,12 +158,13 @@ mdeck send talk.md           # one file to email, with a PDF inside
 ## What you get
 
 - **Layouts:** title, chapter, big statement, image and text, split, full-bleed image, and plain content slides, with points that appear one at a time.
-- **Looks:** four built-in themes and five colour palettes, each light or dark, changeable without touching the slides. Install more from the [theme repository](https://gh.tschieber.de/mdeck-themes/) with `mdeck themes install`, or make your own as small `extension.toml` folders beside the deck.
+- **Looks:** six built-in themes and six colour palettes, each light or dark, changeable without touching the slides. Install more from the [theme repository](https://gh.tschieber.de/mdeck-themes/) with `mdeck themes install`, or make your own as small `extension.toml` folders beside the deck.
 - **One launch page:** `mdeck run` opens a page with a live preview, the presenter and audience views, the deck and reader views, the editor, the guides, one-click builds and PDF, the deck's check results, and for decks with a server its health and the presenter code.
 - **Presenting:** a presenter view with notes and timer, and an audience window that stays in sync.
-- **Drawing on slides:** pen with pressure, highlighter and a fading marker, with a mouse, a finger or an iPad pencil (`D`). Drawings are saved in `<deck>.drawings.json` beside the deck and appear in every view, build and PDF. An iPad can present on its own, or pair with the laptop through a QR code on the launch page while the laptop's audience window follows it.
+- **Drawing on slides:** pen with pressure, highlighter and a laser pointer, with a mouse, a finger or an iPad pencil (`D`). Drawings are saved in `<deck>.drawings.json` beside the deck and appear in every view, build and PDF. An iPad can present on its own, or pair with the laptop through a QR code on the launch page while the laptop's audience window follows it.
 - **Audience questions:** `<poll room="lunch" options="A|B|C" />` shows live results and a QR code; people vote on their phones. `<scale>`, `<wordcloud>` and `<question>` ask for a rating, words or open answers, and `<qrcode join />` shows the join code once for all of them. Rooms run inside `mdeck run --network` or on a small server (`mdeck server`).
 - **Sharing:** a reader view with an outline, a phone-friendly Read mode and a PDF download; speaker notes are stripped from shared builds, and interactive slides appear in their finished state.
+- **Citations:** cite with `[@key]` from BibTeX, CSL-JSON or Hayagriva files; each slide lists its references at its foot, `<bibliography />` lists them all, in any CSL style.
 - **Content:** pictures, video, tables, callouts, code with syntax highlighting and live execution, formulas, QR codes, and your own Preact components, kept with one deck or shared between decks.
 - **New designs on request:** ask your assistant for a palette, theme, layout or interactive component; it keeps them as small folders beside the deck.
 - **Editing in the browser:** `mdeck edit talk.md` opens an editor with a live preview and forms for slides and settings, and `mdeck design` shows themes and palettes on a sample deck for fine-tuning. It writes back into your text file.

package/docs/site/assets/site.css

@@ -68,6 +68,16 @@ h1 { font-size: clamp(32px, 3vw, 46px); margin: 0 0 24px; max-width: 23ch; }
 .welcome h1 { font-size: clamp(40px, 4.5vw, 63px); line-height: 1.08; max-width: 14ch; letter-spacing: -.055em; }
 .welcome article > p:first-of-type { font-size: 20px; line-height: 1.55; color: var(--secondary); max-width: 53ch; }
 .welcome article > p:nth-of-type(3) > a { display: inline-block; background: var(--blue); color: white; text-decoration: none; padding: 10px 19px; border-radius: 5px; font-size: 15px; font-weight: 600; }
+.welcome article { max-width: 820px; }
+.welcome article > :not(.features) { max-width: 76ch; }
+.features { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 36px 32px; margin: 24px 0 32px; }
+.features section { display: flex; flex-direction: column; }
+.features section > p:first-child { order: -1; margin: 0 0 14px; }
+.features section > p:first-child a { margin: 0; }
+.features img { aspect-ratio: 9 / 5; object-fit: contain; background: #e9ecef; }
+.features h3 { margin: 0 0 8px; font-size: 18px; line-height: 1.3; }
+.features section > p:last-child { margin: 0; font-size: 15px; line-height: 1.55; }
+@media (max-width: 720px) { .features { grid-template-columns: 1fr; } }
 h2 { font-size: 28px; margin: 52px 0 17px; }
 h3 { font-size: 21px; margin: 32px 0 12px; }
 p { margin: 0 0 20px; }
@@ -104,8 +114,19 @@ blockquote p:last-child { margin: 0; }
 .slide-example iframe { display: block; width: calc(100% - 36px); aspect-ratio: 16 / 9; margin: 0 18px; border: 0; background: white; box-shadow: 0 3px 9px #20314815; }
 .preview-controls { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 13px 18px; font-size: 12px; }
 .preview-controls > div { display: flex; align-items: center; gap: 7px; }
+.theme-picker { display: grid; grid-template-columns: repeat(auto-fill, minmax(84px, 1fr)); gap: 6px; padding: 0 14px 14px; }
+.theme-picker button { min-width: 0; display: flex; flex-direction: column; gap: 5px; align-items: stretch; padding: 4px 4px 6px; border: 2px solid transparent; border-radius: 7px; background: transparent; font-size: 12px; color: #344d80; cursor: pointer; }
+.theme-picker img { display: block; width: 100%; height: auto; aspect-ratio: 16 / 9; border-radius: 4px; box-shadow: 0 1px 4px #20314826; border: 0; }
+.theme-picker button:hover { border-color: #bdcce9; }
+.theme-picker button[aria-checked="true"] { border-color: var(--blue); background: white; color: var(--blue); font-weight: 600; }
+.appearance-switch { display: flex; }
+.appearance-switch button { border-radius: 0; }
+.appearance-switch button:first-child { border-radius: 4px 0 0 4px; }
+.appearance-switch button:last-child { border-radius: 0 4px 4px 0; margin-left: -1px; }
+.appearance-switch button[aria-checked="true"] { background: var(--blue); border-color: var(--blue); color: white; }
 .preview-controls button, .preview-controls select { padding: 5px 9px; border: 1px solid #bdcce9; background: white; border-radius: 4px; font-size: 12px; }
 .preview-controls button:hover { border-color: var(--blue); color: var(--blue); }
+.preview-controls .appearance-switch button[aria-checked="true"]:hover { color: white; filter: brightness(.9); }
 .preview-controls output { margin-left: 5px; color: #344d80; }
 .preview-controls label { display: flex; align-items: center; gap: 7px; color: #344d80; }
 .page-outline { position: sticky; top: 120px; align-self: start; font-size: 12px; max-height: calc(100dvh - 150px); overflow: auto; padding-left: 18px; border-left: 1px solid var(--rule); margin-top: 53px; }

package/docs/site/assets/site.js

@@ -79,21 +79,31 @@ for (const button of document.querySelectorAll('[data-copy]')) {
 
 for (const example of document.querySelectorAll('[data-preview]')) {
   const frame = example.querySelector('iframe')
-  const output = example.querySelector('output')
   let index = 0
-  for (const button of example.querySelectorAll('[data-control]')) {
-    button.addEventListener('click', () => frame.contentWindow.postMessage({ deckControl: { command: button.dataset.control } }, location.origin))
+  // Theme pictures and light or dark: the deck reloads in the new look on
+  // the same slide. Light or dark starts on each theme's own.
+  const themes = [...example.querySelectorAll('[data-theme]')]
+  const switches = [...example.querySelectorAll('[data-set-appearance]')]
+  let theme = themes.find(button => button.getAttribute('aria-checked') === 'true') ?? themes[0]
+  let appearance = theme?.dataset.appearance ?? 'light'
+  const show = () => {
+    for (const button of themes) button.setAttribute('aria-checked', String(button === theme))
+    for (const button of switches) button.setAttribute('aria-checked', String(button.dataset.setAppearance === appearance))
   }
-  example.querySelector('select').addEventListener('change', event => {
+  const reload = () => {
     const url = new URL(frame.src)
-    url.searchParams.set('theme', event.target.value)
+    url.searchParams.set('theme', theme.dataset.theme)
+    url.searchParams.set('appearance', appearance === theme.dataset.appearance ? '' : appearance)
     url.hash = String(index + 1)
     frame.src = url.toString()
-  })
+    show()
+  }
+  for (const button of themes) button.addEventListener('click', () => { theme = button; appearance = button.dataset.appearance; reload() })
+  for (const button of switches) button.addEventListener('click', () => { appearance = button.dataset.setAppearance; reload() })
+  show()
   window.addEventListener('message', event => {
     if (event.source !== frame.contentWindow || event.origin !== location.origin || !event.data?.deckStateChanged) return
     index = event.data.deckStateChanged.index
-    output.textContent = `Slide ${index + 1}`
   })
 }
 

package/docs/site/build.js

@@ -38,11 +38,19 @@ function navigation(current) {
 
 const exampleFiles = { 'first-talk': resolve(docsRoot, 'examples/first-talk.md'), 'custom-layouts': resolve(projectRoot, 'examples/custom-layouts/slides.md') }
 
-// The theme picker lists every registered theme and starts on the example's own design.
-function themeOptions(exampleFile) {
+// The theme picker: every registered theme as a picture of the example's
+// chart slide in it (images/themes/<theme>-thumb.webp, from
+// tools/feature-images.mjs), the example's own theme first and chosen; and light
+// or dark, starting on the theme's own.
+function themePicker(exampleFile) {
   const current = parseSlides(readFileSync(exampleFile, 'utf8')).deckConfig.theme ?? 'neue'
-  const themes = loadRegistry(exampleFile).themes
-  return Object.values(themes).map(theme => `<option value="${theme.id}"${theme.id === current ? ' selected' : ''}>${escape(theme.title)}</option>`).join('')
+  const themes = Object.values(loadRegistry(exampleFile).themes).sort((x, y) => (y.id === current) - (x.id === current))
+  const buttons = themes.map(theme => {
+    const thumb = `images/themes/${theme.id}-thumb.webp`
+    const picture = existsSync(resolve(docsRoot, thumb)) ? `<img src="${thumb}" alt="" width="160" height="90" loading="lazy">` : ''
+    return `<button type="button" role="radio" aria-checked="${theme.id === current}" data-theme="${theme.id}" data-appearance="${theme.manifest.appearance ?? 'light'}">${picture}<span>${escape(theme.title)}</span></button>`
+  }).join('')
+  return `<div class="theme-picker" role="radiogroup" aria-label="Theme">${buttons}</div>`
 }
 
 function preview(page) {
@@ -50,8 +58,9 @@ function preview(page) {
   const custom = page.preview === 'custom-layouts'
   return `<figure class="slide-example" data-preview>
     <figcaption><span>${custom ? 'A reusable comparison design' : 'A presentation you can try'}</span><a href="examples/${page.preview}.html?palette=&amp;appearance=" target="_blank" rel="noopener">Open slides</a></figcaption>
-    <iframe title="${custom ? 'Comparison slide example' : 'Example presentation'}" src="examples/${page.preview}.html?embedded=1&amp;palette=&amp;appearance=" loading="lazy"></iframe>
-    <div class="preview-controls"><div><button type="button" data-control="prev" aria-label="Previous slide or point">Previous</button><button type="button" data-control="next" aria-label="Next slide or point">Next</button><output aria-live="polite">Slide 1</output></div><label>Look <select aria-label="Example theme">${themeOptions(exampleFiles[page.preview])}</select></label></div>
+    <iframe title="${custom ? 'Comparison slide example' : 'Example presentation'}" src="examples/${page.preview}.html?embedded=1&amp;controls=1&amp;draw=1&amp;palette=&amp;appearance=" loading="lazy"></iframe>
+    <div class="preview-controls"><span>Move the pointer over the slides for their controls, or use the arrow keys. Press D to draw.</span><div class="appearance-switch" role="radiogroup" aria-label="Light or dark"><button type="button" role="radio" data-set-appearance="light">Light</button><button type="button" role="radio" data-set-appearance="dark">Dark</button></div></div>
+    ${themePicker(exampleFiles[page.preview])}
   </figure>`
 }
 

package/docs/site/content/commands.md

@@ -141,9 +141,10 @@ The check takes a few seconds and needs Chrome or Chromium; set `MDECK_CHROME` t
 ```sh
 mdeck snapshot my-talk.md
 mdeck snapshot my-talk.md --slide 3,5-7 --dark
+mdeck snapshot my-talk.md --sheet
 ```
 
-This saves each slide, with all steps revealed, as a 1280×720 PNG file in `.mdeck-snapshots/` beside the deck (`-o` for another folder), named `my-talk-03.png` and so on, and prints the paths. `--slide` picks slides by number; `--dark` and `--light` show that appearance instead of the deck's own. An AI assistant that reads pictures can use them to look at what it wrote. If you keep your slides in Git, add `.mdeck-snapshots/` to your `.gitignore`.
+This saves each slide, with all steps revealed, as a 1280×720 PNG file in `.mdeck-snapshots/` beside the deck (`-o` for another folder), named `my-talk-03.png` and so on, and prints the paths. `--slide` picks slides by number; `--dark` and `--light` show that appearance instead of the deck's own. `--sheet` saves one picture instead, `my-talk-sheet.png`: the slides in a grid, each under its number and heading, to see a whole deck at a glance. An AI assistant that reads pictures can use them to look at what it wrote. If you keep your slides in Git, add `.mdeck-snapshots/` to your `.gitignore`.
 
 ## Layouts, themes and palettes
 

package/docs/site/content/drawing.md

@@ -32,7 +32,7 @@ Drawings live in a file next to your slides: `my-talk.drawings.json` for `my-tal
 - 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`:
+Builds and PDFs include the drawings. In the reader view, which a file from `mdeck send` opens in, a **Drawings** button hides and shows them, also for **Save as PDF**; the browser remembers the choice. To leave them out of a build altogether, add `--no-drawings`:
 
 ```sh
 mdeck pdf my-talk.md --no-drawings

package/docs/site/content/sharing.md

@@ -18,7 +18,7 @@ mdeck send my-talk.md
 
 Send `my-talk.html` by email. It opens in a **reader view**: an outline of all slides on the left, the slides in the middle, a **Read** mode that stacks every slide for scrolling on a phone, a **Light**/**Dark** button, a **Download PDF** button, and a **Present** button that opens standalone slides. The PDF is inside the file, so there is nothing else to attach.
 
-- Drawings from `my-talk.drawings.json` are part of every build and PDF; `--no-drawings` leaves them out. See [Draw on your slides](drawing.html).
+- Drawings from `my-talk.drawings.json` are part of every build and PDF; `--no-drawings` leaves them out. Readers can hide them with the **Drawings** button in the reader view. See [Draw on your slides](drawing.html).
 - Your speaker notes are removed. Add `--notes` to keep them in the file, for example when you also present from the same file. Readers only see notes if you put `reader:` with `notes: true` in the settings at the top of your slide file.
 - Slides with a poll, question, word cloud or scale stay as a record of the talk: the question and its options, marked as answered live. Add `--no-polls` to leave them out of the file and its PDF, together with slides showing the join code (`<qrcode join />`).
 - The PDF is made while sending, using Chrome or Chromium on your computer. If neither is found, the button offers the browser's own "Save as PDF" dialog instead. Set `MDECK_CHROME` to the browser's path if it is installed somewhere unusual. `--no-pdf` skips it.

package/docs/site/content/welcome.md

@@ -6,6 +6,74 @@ The content stays yours. The assistant works from your material, not from its ow
 
 [Make your first presentation](getting-started.html)
 
+## What you can do with it
+
+<div class="features">
+
+<section>
+
+[![The presenter view on an iPad with circles, an arrow and a highlight drawn on a chart slide, and the projector behind it showing the same strokes](images/features/drawing.webp)](images/features/drawing.webp)
+
+### Draw on your slides, from an iPad if you like
+
+Circle a number, underline a phrase, point with a laser. Pair an iPad by scanning a code, and it becomes your presenter screen and drawing pad while the laptop drives the projector: every stroke shows on the big screen as you draw. Drawings are kept with the talk, in its PDF too. [Draw on your slides](drawing.html)
+
+</section>
+
+<section>
+
+[![A poll slide with live bars and a QR code, and a phone showing the same question with one answer picked](images/features/polls.webp)](images/features/polls.webp)
+
+### Ask the room, and show the answers on the slide
+
+Polls, scales, word clouds, open questions and numbers to guess. People scan the code and answer on their phones, no app needed, and the bars grow as votes come in. Close the vote, discuss, reveal the right answer. The answers are kept with the talk. [Ask your audience](audience.html)
+
+</section>
+
+<section>
+
+[![A slide with author–year citations and the full references at its foot, next to a slide that lists all references](images/features/citations.webp)](images/features/citations.webp)
+
+### Cite your sources properly
+
+Cite as in a paper, `[@knuth1984, p. 97]`, from the BibTeX, CSL-JSON or Hayagriva file you already keep. Each slide lists what it cites at its foot, and a references slide lists everything, in APA, Vancouver, Harvard or any CSL style. [Cite a source](more-content.html#cite-a-source)
+
+</section>
+
+<section>
+
+[![The same chart slide in six themes: neue, plain, work, academic, minimal and glass](images/features/themes.webp)](images/features/themes.webp)
+
+### Write the content once, change the look anytime
+
+The file holds what you say; a theme and a palette decide how it looks. One line changes every slide, light or dark, and your text never moves. Six themes come with mdeck, more are one command away in the [theme repository](https://gh.tschieber.de/mdeck-themes/). [Change the look](appearance.html)
+
+</section>
+
+<section>
+
+[![A slide with a short Python example and its output below it](images/features/code.webp)](images/features/code.webp)
+
+### Run code on the slide
+
+Give a Python or JavaScript example a Run button, change it in front of the audience and run it again. Python runs right in the browser, with packages such as NumPy and pandas, so nothing needs installing. [Show a code example](more-content.html#show-a-code-example)
+
+</section>
+
+<section>
+
+[![The reader view of a talk on a laptop, with an outline of the slides, and on a phone in reading mode](images/features/reader.webp)](images/features/reader.webp)
+
+### Send one file that anyone can open
+
+`mdeck send` makes a single HTML file for the people you send the talk to: an outline, a reading mode for phones, light and dark, and the PDF inside. It opens in any browser, also offline, and your speaker notes stay out. [Send, host or print](sharing.html)
+
+</section>
+
+</div>
+
+Also: a presenter view with notes, timer and the next slide; points revealed one at a time; pictures, videos and formulas; a browser editor for those who prefer clicking; and a launch page (`mdeck run`) that gathers it all, with a check for missing pictures and slides that do not fit.
+
 <!-- preview -->
 
 ## Bring your material, then shape it
@@ -52,13 +120,9 @@ The `#` makes a heading. The line with `---` starts another slide. A dash before
 - **Which view or server do I need?** See [Views, commands and servers](views.html).
 - **Something looks wrong?** Try [the troubleshooting guide](troubleshooting.html).
 
-## What mdeck does today
-
-mdeck gives you ready-made slide layouts, different visual themes, speaker notes, pictures, videos, a separate presenter view, drawing on slides (also from an iPad), polls and other questions your audience answers on their phones, and a reader view with a PDF for people you send the slides to. It can also use layouts, themes and colors made for your team, and your assistant can make new ones for a single talk.
-
-`mdeck run` opens a launch page for your talk with all of this in one place: the presenter view, the editor, these guides, buttons that make the files to share, and a check for missing pictures.
+## Your file, whoever edits it
 
-Whoever writes the slides, your assistant, a text editor, or the built-in browser editor (`mdeck edit`), the file stays the single copy, and the preview updates as it changes.
+Whoever writes the slides, your assistant, a text editor, or the built-in browser editor (`mdeck edit`), the file stays the single copy, and the preview updates as it changes. mdeck can also use layouts, themes and colours made for your team, and your assistant can make new ones for a single talk.
 
 ## Keep this guide nearby
 

package/docs/site/examples/chart.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 900"><rect width="820" height="900" fill="var(--surface, #f2f2f2)"/>
+<g stroke="var(--rule, #ddd)" stroke-width="2"><path d="M60 760H780"/><path d="M60 585H780"/><path d="M60 410H780"/><path d="M60 235H780"/></g>
+<rect x="90" y="550" width="70" height="210" rx="5" fill="var(--muted, #888)"/><rect x="205" y="480" width="70" height="280" rx="5" fill="var(--muted, #888)"/><rect x="320" y="130" width="70" height="630" rx="5" fill="var(--accent, #888)"/><rect x="435" y="410" width="70" height="350" rx="5" fill="var(--muted, #888)"/><rect x="550" y="550" width="70" height="210" rx="5" fill="var(--muted, #888)"/><rect x="665" y="620" width="70" height="140" rx="5" fill="var(--muted, #888)"/>
+<g fill="var(--muted, #666)" font-family="sans-serif" font-size="30" text-anchor="middle"><text x="125" y="815">A</text><text x="240" y="815">B</text><text x="355" y="815">C</text><text x="470" y="815">D</text><text x="585" y="815">E</text><text x="700" y="815">F</text></g>
+</svg>

package/docs/site/examples/first-talk.drawings.json

@@ -0,0 +1 @@
+{"version":1,"width":1920,"height":1080,"slides":{"draw":[{"id":"peak","tool":"pen","color":"#e11d48","size":7,"points":[[427,193,0.45],[434,188,0.47],[443,182,0.48],[453,178,0.5],[464,175,0.52],[476,174,0.54],[487,173,0.55],[499,175,0.57],[510,177,0.59],[520,181,0.6],[530,186,0.62],[538,191,0.63],[546,197,0.65],[553,203,0.66],[559,209,0.67],[564,216,0.69],[569,223,0.7],[573,230,0.71],[577,237,0.72],[580,245,0.73],[581,252,0.74],[582,261,0.75],[581,269,0.76],[579,277,0.77],[575,285,0.78],[569,293,0.78],[561,299,0.79],[553,305,0.79],[543,309,0.79],[533,312,0.8],[522,314,0.8],[511,315,0.8],[501,315,0.8],[491,315,0.8],[481,314,0.8],[471,312,0.79],[461,311,0.79],[452,309,0.79],[443,307,0.78],[433,304,0.78],[424,301,0.77],[415,297,0.76],[407,292,0.75],[400,286,0.74],[394,280,0.73],[389,272,0.72],[386,265,0.71],[385,257,0.7],[386,249,0.69],[388,241,0.67],[391,233,0.66],[396,226,0.65],[401,220,0.63],[407,214,0.62],[414,209,0.6],[421,204,0.59],[428,199,0.57],[436,194,0.55],[444,190,0.54],[453,186,0.52],[463,182,0.5],[473,179,0.48],[484,177,0.47],[496,176,0.45]]},{"id":"arrow","tool":"pen","color":"#e11d48","size":7,"points":[[600,215,0.45],[615,215,0.49],[630,215,0.53],[644,215,0.57],[659,215,0.61],[674,216,0.64],[689,218,0.67],[704,220,0.7],[719,223,0.73],[733,226,0.75],[748,230,0.77],[763,236,0.79],[778,242,0.79],[793,249,0.8],[807,257,0.8],[822,266,0.79],[837,275,0.79],[852,286,0.77],[867,298,0.75],[881,310,0.73],[896,323,0.7],[911,337,0.67],[926,352,0.64],[941,367,0.61],[956,382,0.57],[970,398,0.53],[985,414,0.49],[1000,430,0.45]]},{"id":"arrow-head","tool":"pen","color":"#e11d48","size":7,"points":[[967,421,0.45],[1000,430,0.8],[993,397,0.45]]}]}}

package/docs/site/examples/first-talk.md

@@ -1,20 +1,41 @@
 ---
-theme: academic
+theme: neue
+meta:
+  title: "A short tour of mdeck"
 show:
   organization: none
   author: none
----
-
+bibliography: references.bib
 ---
 :::meta
 layout: title
+image: ./mdeck.svg
+fit: contain
+alt: "A Markdown file turning into a stack of slides"
 id: hello
 :::
-# Write it down.
-## Why every lab keeps a notebook
+# Slides from a text file.
+## A short tour of mdeck
+
+:::notes
+These notes are only for you: they show in the presenter view.
+:::
+
+---
+:::meta
+id: how-it-works
+:::
+# From your material to a talk
+
+:::steps
+- Hand your slides, papers or notes to an AI assistant
+- It writes one Markdown file with your content
+- mdeck presents it in the browser
+- Send it as one file, or as a PDF
+:::
 
 :::notes
-Ask who has ever repeated an experiment because nobody remembered how it was done.
+Press Next: the points appear one at a time.
 :::
 
 ---
@@ -22,67 +43,136 @@ Ask who has ever repeated an experiment because nobody remembered how it was don
 layout: split
 props:
   ratio: [1, 1]
+id: write-this
 :::
-# A notebook answers three questions.
+# Write this, get a slide
+
+:::slot left
+```markdown
+# Three ideas
 
-- What did I do?
-- What did I see?
-- What would I change?
+- Start small
+- Show an example
+- Ask a question
+```
+:::
 
-:::notes
-Everything else in a good notebook serves one of these three questions.
+:::slot right
+A `#` makes the heading, a dash a point, and `---` starts the next slide. Your assistant writes it; you can read and change every word.
 :::
 
 ---
 :::meta
 layout: focus
-attribution: "A saying in many labs"
 :::
-# If it is not written down, it did not happen.
+# Your talk is a text file: you can read it, change it and keep it.
 
 ---
+
 :::meta
 layout: chapter
 number: 1
-part: "Good habits"
+part: "In the room"
 :::
-# Write as you work.
+# Present it, live.
 
-Two habits that make a notebook useful a year later.
+Draw, ask the room, cite and run code, right on the slides.
 
 ---
 :::meta
-layout: split
-props:
-  ratio: [1, 1]
+layout: image-text
+image: ./chart.svg
+alt: "A bar chart with one bar much taller than the others"
+id: draw
 :::
-# Two habits that pay off
+# Draw while you talk
 
-:::slot left
-## Date every page
-The date and the experiment's name come first, before anything else.
+- Circle, underline, point with a laser
+- From an iPad paired with the laptop
+- Saved with the slide, also in the PDF
+
+:::notes
+The circle and the arrow were drawn on this slide and stay with it.
 :::
 
-:::slot right
-## Record what went wrong
-Failed runs explain the successful ones. Never tear out a page.
+---
+:::meta
+id: first
+:::
+# Which will you try first?
+
+<poll room="first" options="Drawing on slides|Polls from phones|Citations|A new theme" />
+
+:::notes
+People answer on their phones and the bars grow live. These answers are kept from a talk.
 :::
 
 ---
 :::meta
-layout: image-text
-image: ./notebook.svg
-alt: "An open lab notebook with written steps, a results table and a plot"
+id: cite
 :::
-# One page per experiment
+# Cite like in a paper
 
-Aim, materials, steps, results and a short conclusion. Glue in printouts so nothing gets lost.
+Slides are Markdown, a plain text format meant to read well as it is [@gruber2004]. Text and code kept together is an old idea [@knuth1984].
+
+Citations use Pandoc's syntax [@pandoc] and any citation style; each slide lists its references at its foot.
+
+---
+:::meta
+id: references
+:::
+# References
+
+<bibliography />
+
+---
+:::meta
+id: run
+:::
+# Run code on the slide
+
+```python live editable
+features = ["drawing", "polls", "citations", "themes"]
+print(", ".join(name.capitalize() for name in features))
+```
+
+:::tip
+Press Run, change the list, run it again.
+:::
+
+---
+:::meta
+layout: chapter
+number: 2
+part: "The look"
+:::
+# Content and style, apart.
+
+The file holds what you say. A theme decides how it looks.
+
+---
+:::meta
+layout: split
+props:
+  ratio: [1, 1]
+:::
+# One file, many looks
+
+:::slot left
+## Themes
+Six come with mdeck, more are one command away. Try the pictures below this deck.
+:::
+
+:::slot right
+## Light or dark
+Every palette has both. Switch while presenting, without touching the file.
+:::
 
 ---
 :::meta
 layout: full-bleed-image
-image: ./notebook.svg
-alt: "An open lab notebook with written steps, a results table and a plot"
+image: ./contours.jpg
+alt: "Contour lines like those on a map"
 overlay: true
 :::
-# Your future self will thank you.
+# Make your next presentation.