mdeck 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 3.3.0 — 2026-10-08
+
+- Citations and references: `bibliography: refs.bib` in the deck settings, then cite in Pandoc's syntax, `[@smith2020, p. 12]`, `[see @a; @b]`, `[-@a]` or `@smith2020` in a sentence. Each citation shows in the style's short form, each slide lists the full references of the works it cites above its footer (`show.citations: false` leaves them out), and `<bibliography />` lists them all on a slide (`part="1/2"` splits a long list). Reference files may be BibTeX (`.bib`), CSL-JSON (`.json`) or Hayagriva (`.yml`, Typst's format), several at once. `csl:` picks the style, `apa` by default, `vancouver`, `harvard1` or any `.csl` file; the style's words follow `lang`. `nocite:` lists works without citing them. Formatting happens at build time, so a deck carries only the finished text. Unknown keys are marked on the slide and reported by `mdeck check`.
+- `mdeck check --render` looks at the deck in Chrome: it builds it, shows every slide with all steps revealed, and reports content that does not fit, text cut off at the slide's edge or hard to read on what is behind it, and errors the page reports, each with the slide's number, heading and line. `mdeck snapshot` saves slides as PNG files (`--slide 3,5-7`, `--dark`, `--light`, `-o`; by default in `.mdeck-snapshots/`), so a person or an assistant can look at them. The slide-writing skill uses both.
+- New view `?view=follow`: people in the room follow the talk on their phone or laptop. It shows the slide the presenter shows, step by step, and their drawing, read from the stage room without sending anything; people can page back and return with **Back to live**, and never see a slide or step before the presenter shows it. `<qrcode follow />` shows its link on a slide, the phones' answer page links to it (**Follow the slides**), and `mdeck run --network` prints it. It works on the same network with `mdeck run --network`, and anywhere for a deck hosted with a `server` setting. Followers count as phones in the presenter's overview of who is connected.
+- Fixed: a web video (YouTube, Vimeo, SwitchTube) in `<videoplayer>`'s click mode went on playing, with sound, after leaving its slide. Leaving the slide now stops it; coming back shows it ready to play.
+- Straight lines snap to steps of 15° (horizontal, vertical, 45° …) when they are within 4° of one, both when a held stroke straightens and when an end point is dragged; further off they stay as drawn.
+- Polls have a button with an eye that shows or hides the results (bars and counts), also in the audience window and on paired devices. `results="hidden"` starts with them hidden, e.g. for peer instruction; the audience then sees no bars, the presenter's own screens show them faint.
+- `--no-polls` leaves slides with a poll, question, word cloud, scale or join code (`<qrcode join />`) out of `mdeck send`, `mdeck build --reader` and `mdeck pdf`. By default they stay as a record of the talk. Drawings stay on their slides.
+
+## 3.2.0 — 2026-10-07
+
+- Pictures written in the text fit on the slide in every theme: a paragraph of nothing but pictures shrinks into the room below the heading instead of running off the slide, keeping its proportions (small pictures keep their size), and several pictures in one paragraph sit side by side. Such paragraphs have the class `pictures`, for themes that set them their own way; a picture in a sentence is left alone.
+- Tables have room below them in every theme, so a sentence after a table no longer sits right against it.
+- `mdeck themes build` also renders an icon for each theme: its title slide at 96×54 (drawn at twice that, about 3 KB), listed as `icon` in `catalogue.json` and `looks.json`. The theme repository's gallery shows it in its list instead of the palette's colours, which said little about a theme.
+
 ## 3.1.0 — 2026-10-07
 
 - Packs are gone: every theme and palette is installed on its own. `mdeck themes install duet` installs the theme with its default palette (`cobalt`), and `mdeck palettes install solarized` a palette; both have `search`, `remove`, `update` and `list`. A palette made for one theme (FHNW's `brand`) brings that theme along and goes with it. A palette an installed theme uses by default is not removed while that theme is there. Installs go into `themes/<id>/` and `palettes/<id>/` of the extensions folder, so a theme and a palette may share a name.

package/assets/base.css

@@ -162,11 +162,35 @@ deck-stage[data-ink-hidden] .slide-ink { display: none; }
 /* ── Code blocks ─────────────────────────────────────────────────────────── */
 .code-block { white-space: pre-wrap; overflow-x: hidden; }
 
+/* ── Pictures written in the text ───────────────────────────────────────── */
+/* A paragraph of nothing but pictures (marked in markedSetup.js) fits into
+   the room the slide has left: a large picture shrinks, keeping its
+   proportions, and never runs off the slide; a small one keeps its size.
+   Several sit side by side. Themes may set them differently (a grid, cropped
+   to fill); a picture in a sentence is left alone. */
+.slide-body p.pictures {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex: 0 1 auto;
+  min-height: 0;
+}
+.slide-body p.pictures > :is(img, .themed-picture) {
+  flex: 0 1 auto;
+  min-width: 0;
+  min-height: 0;
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+}
+
 /* ── Tables ──────────────────────────────────────────────────────────────── */
 .slide-body table {
   border-collapse: collapse;
   width: 100%;
   font-size: var(--fs-body);
+  /* Room before what follows, such as a sentence about the numbers. */
+  margin-bottom: calc(var(--gap-item, 24px) * 1.5);
 }
 .slide-body th,
 .slide-body td {

package/assets/extensions/themes/academic/styles.css

@@ -579,6 +579,21 @@ strong { color: var(--ink); font-weight: 700; }
 }
 .slide-footnotes li { line-height: 1.4; }
 .slide-body sup { color: var(--accent); font-weight: 600; }
+.slide-citations { font-family: var(--font-body); }
+.slide-citations:not(.slide-footnotes + .slide-citations) {
+  border-top: 0;
+  position: relative;
+  padding-top: 14px;
+}
+.slide-citations:not(.slide-footnotes + .slide-citations)::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 280px;
+  height: 1px;
+  background: var(--ink-soft);
+}
 
 /* ─────────────────────────────────────────────
    CODE — a listing on the surface, a rule at its side

package/docs/reference/authoring.md

@@ -63,6 +63,10 @@ Each `---` line starts a new slide. Frontmatter is only needed when you want a s
 | `params` | — | Theme-specific color/font overrides (see below) |
 | `reader.themes` | `true` | Whether the reader view offers a switch between light and dark (see below) |
 | `reader.notes` | `false` | Whether the reader view shows speaker notes under each slide in Read mode |
+| `bibliography` | — | Reference file, or a list of them, relative to the deck: `.bib`, `.json` (CSL-JSON) or `.yml` (Hayagriva) (see [Citations](#citations-and-references)) |
+| `csl` | `apa` | Citation style: `apa`, `vancouver`, `harvard1`, or a `.csl` file |
+| `nocite` | — | References to list without citing them; `['*']` lists the whole file |
+| `show.citations` | `true` | `false` leaves out each slide's own references above the footer |
 
 ### Theme params
 
@@ -87,7 +91,8 @@ reader:
 ```
 
 Views are chosen with one address parameter: `?view=deck`, `?view=reader`,
-`?view=presenter` or `?view=audience`. `mdeck send` produces a file that opens
+`?view=presenter`, `?view=audience` or `?view=follow` (the presenter's slide and
+ink on another device, read from the stage room; never ahead of the presenter). `mdeck send` produces a file that opens
 in the reader view (outline, Read mode, a light/dark switch, PDF download).
 The file carries only the deck's own theme and palette, with that theme's
 fonts, so readers see the deck as it was made; they can switch between its
@@ -376,6 +381,52 @@ This claim needs a source.[^1]
 [^1]: The source citation goes here.
 ```
 
+### Citations and references
+
+Name a reference file in the deck frontmatter and cite its entries by key, in the syntax Pandoc and Quarto use:
+
+```markdown
+---
+bibliography: refs.bib
+csl: apa
+---
+# Results
+
+As @smith2020 showed, it works [see @smith2020, p. 12; @doe2019].
+
+---
+# References
+
+<bibliography />
+```
+
+| Written | APA | Vancouver |
+|---|---|---|
+| `[@smith2020]` | (Smith et al., 2020) | (1) |
+| `[@smith2020, p. 12]` | (Smith et al., 2020, p. 12) | (1) |
+| `[see @smith2020; @doe2019]` | (see Smith et al., 2020; Doe, 2019) | (1,2) |
+| `[-@smith2020]` | (2020) | (1) |
+| `@smith2020` | Smith et al. (2020) | Smith et al. (1) |
+| `@smith2020 [chap. 3]` | Smith et al. (2020, Chapter 3) | Smith et al. (1) |
+
+- **On the slide** each citation shows in the style's short form, and the full reference of every work the slide cites stands in small type above the footer, after any footnotes. `show.citations: false` leaves those out.
+- **`<bibliography />`** lists every cited work, plus those named in `nocite`, in the style's order. A list too long for one slide goes on several: `<bibliography part="1/2" />` on one and `<bibliography part="2/2" />` on the next split it in halves.
+- **Locators** after a comma: `p.`/`pp.`, `chap.`, `sec.`, `fig.`, `vol.`, `para.`, `no.`, `l.`, `eq.` and the German `S.`, `Kap.`, `Abb.`, `Bd.`, `Nr.`; a bare number is a page.
+- **`@key` without brackets** is a citation only when the key is in the reference file, so e-mail addresses and `@handles` stay text. Citations in code, in links' addresses and in `:::notes` blocks work as in slide text, except that notes show no reference footer.
+- **A key that is not in the file** shows as `@key?`, marked, and `mdeck check` and `mdeck build` warn about it.
+
+**Reference files.** `bibliography` takes one file or a list:
+
+| Extension | Format | Comes from |
+|---|---|---|
+| `.bib` | BibTeX / BibLaTeX | Zotero, JabRef, Google Scholar, most journals |
+| `.json` | CSL-JSON | Zotero ("CSL JSON"), Pandoc |
+| `.yml`, `.yaml` | Hayagriva (Typst), or CSL-YAML when the file is a list | Typst projects |
+
+**Styles.** `apa`, `vancouver` and `harvard1` are built in. Any other style from the [CSL style repository](https://www.zotero.org/styles) works as a file next to the deck: `csl: nature.csl`. The style's words (`p.`/`S.`, `and`/`und`, `et al.`/`u. a.`) follow the deck's `lang`; English, German, French, Spanish and Dutch are included, other languages fall back to English. Note styles (such as Chicago notes-bibliography) are written for footnotes; on slides an author-date or numeric style reads better.
+
+The references are formatted when the deck is built, so the deck carries only the finished text and works offline; the dev server reformats them when the deck or a reference file changes.
+
 ---
 
 ## Code blocks
@@ -533,6 +584,12 @@ labels:
 | `respond.send` | Send | Senden |
 | `respond.sent` | Sent. Thank you! | Gesendet. Danke! |
 | `join.scan` | Scan to join | Scannen und mitmachen |
+| `follow.scan` | Scan to follow the slides | Scannen und Folien mitverfolgen |
+| `follow.open` | Follow the slides | Folien mitverfolgen |
+| `follow.live` | Live | Live |
+| `follow.back` | Back to live | Zur aktuellen Folie |
+| `follow.waiting` | The talk has not started yet. | Der Vortrag hat noch nicht begonnen. |
+| `follow.tryHere` | Try following here | Mitverfolgen hier ausprobieren |
 | `question.empty` | Answers appear here. | Hier erscheinen die Antworten. |
 | `scale.average` | Average {n} | Durchschnitt {n} |
 
@@ -594,6 +651,19 @@ Reference images with standard Markdown syntax or the `image:` frontmatter field
 ![Alt text](./img/diagram.png)
 ```
 
+A paragraph of nothing but pictures fits into the room the slide has left: a
+large picture shrinks, keeping its proportions, and a small one keeps its
+size. Several pictures in one paragraph sit side by side:
+
+```markdown
+# Three mornings
+
+![Fjord](./img/fjord.jpg) ![Mountains](./img/mountains.jpg) ![Snow](./img/snow.jpg)
+```
+
+A picture inside a sentence stays in the sentence. Themes may set picture
+paragraphs their own way (Lightbox fills a grid edge to edge).
+
 A local SVG whose source contains `var(--…)` is drawn inline instead of as an
 `<img>`, both in slide text (`![…](./img/drawing.svg)` or `<img src>`) and as a
 layout's `image` (`title`, `chapter`, `image-text`, `full-bleed-image`, and
@@ -676,6 +746,7 @@ For `play="auto"` the video pauses and resets to the beginning when you navigate
 | `question` | — | Question text; phones fall back to the slide heading |
 | `qr` | `true` | `false` leaves out the QR code (shown earlier with `<qrcode join />`) |
 | `answer` | — | The right answer (several separated by `\|`): a button with a tick outlines its label, bar and count in green, also in the audience window and on paired devices. `--poll-correct` sets the colour |
+| `results` | — | `hidden` starts with the results hidden, e.g. for peer instruction. A button with an eye shows or hides them (bars and counts) at any time, also in the audience window and on paired devices. Hidden, the audience window shows no bars; the presenter's own screens show them faint |
 
 Three more activities take the same `room`, `question` and `qr`:
 
@@ -685,10 +756,12 @@ Three more activities take the same `room`, `question` and `qr`:
 | `<wordcloud>` | `placeholder`, `limit` (60), `height` (520) | Text field, up to 40 characters, repeatable | A packed word cloud (d3-cloud): size by frequency, some words upright, case-insensitive |
 | `<question>` | `placeholder`, `limit` (8) | Text field, up to 200 characters, repeatable | The newest answers as cards |
 
-`<qrcode join />` shows the deck's join code large with its link (`size`, default 420), for a slide that invites everyone once; activities after it can use `qr="false"`. QR codes (`<qrcode>`, activities) are SVG in the slide's `--ink` on a transparent background; `--qr-ink` and `--qr-bg` override the colours.
+`<qrcode follow />` shows the link for following the slides on phones and laptops (`?view=follow`), with `mdeck run --network` or a hosted deck with a `server` setting; the phones' answer page links to it as well. `<qrcode join />` shows the deck's join code large with its link (`size`, default 420), for a slide that invites everyone once; activities after it can use `qr="false"`. QR codes (`<qrcode>`, activities) are SVG in the slide's `--ink` on a transparent background; `--qr-ink` and `--qr-bg` override the colours.
 
 The slide shows live bars, the number of answers, a QR code and a short link. Phones never load the deck: they open the server's own answer page at `<server>/<code>`, where the six-digit session code is the same for every poll in the deck. The presenter's screen (the presenter view or a full deck window, never an embedded preview) announces the poll on the current slide with what the phones should show and the deck's look; the server only accepts that from the presenter. Between polls the phones wait. Each device's latest vote counts. The presenter can reset the room (hover over the results).
 
+`--no-polls` leaves slides with an activity or a join code (`<qrcode join />`) out of `mdeck send`, `mdeck build --reader` and `mdeck pdf`; without it they show as a record of the talk. Saved drawings follow the remaining slides.
+
 Rooms run inside `mdeck run` (add `--network` so phones can reach it) or on a server started with `mdeck server`, set in the deck:
 
 ```yaml

package/docs/reference/extensions.md

@@ -246,7 +246,9 @@ touch files changed since then unless given `--force`.
 
 The repository serves `catalogue.json` (`{ schema: 2, themes: [...],
 palettes: [...] }`, each with its id, version, default palette or theme,
-`url`, `sha256`, `preview`, and `builtIn` for those that come with mdeck) and
+`url`, `sha256`, `preview`, for a theme an `icon` (its title slide at
+96×54, drawn at twice that for sharp screens), and `builtIn` for those that
+come with mdeck) and
 one JSON file per version holding the text of its files.
 `mdeck themes build <repository> -o <out> [--check]` writes both from a
 folder with `themes/` and `palettes/`; `MDECK_THEMES_URL` points mdeck at

package/docs/site/content/audience.md

@@ -73,6 +73,12 @@ Each question shows the QR code unless you say otherwise. To invite everybody on
 
 The code is drawn in the slide's colours, so it fits the theme; phone cameras also read light codes on dark slides.
 
+### Follow the slides on a phone
+
+`<qrcode follow />` shows a code that opens your slides on people's phones and laptops, following you: the slide you show, step by step, and what you draw. They can page back to read something again and return with **Back to live**; slides you have not shown yet stay hidden. The phones' answer page links to it too (**Follow the slides**), so one join code can do both.
+
+It needs their devices to reach your slides: present with `mdeck run --network` when everyone is on the same Wi-Fi (it prints the **Follow** address), or host the built deck with a `server` setting for people anywhere.
+
 Hover over the results to see **Reset**, which clears the answers, for example before the real session. Only the presenter can reset.
 
 ## How phones and slides meet

package/docs/site/content/commands.md

@@ -16,7 +16,8 @@ For how the commands, the views and the servers fit together, see [Views, comman
 | `mdeck palettes search`, `install <palette>`, … | The same for palettes |
 | `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 check my-talk.md` | Check settings and look for missing local files; `--render` also finds slides whose content does not fit |
+| `mdeck snapshot my-talk.md` | Save pictures of the slides as PNG files, for you or your assistant to look at |
 | `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 |
@@ -86,14 +87,15 @@ The design page shows themes and palettes on a sample deck with every kind of sl
 | 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 --reader` | A hosted reader folder with speaker notes removed; add `--notes` to retain them, `--no-polls` to leave out the slides with polls and their join codes |
 | `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-polls` | The same, leaving out the slides with polls and their join codes |
 | `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 |
+| `mdeck pdf my-talk.md -o talk.pdf` | Render the slides to a PDF file (`--no-polls` leaves out the slides with polls) |
 | `--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.
@@ -117,7 +119,29 @@ 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.
+## Check how the slides look
+
+```sh
+mdeck check my-talk.md --render
+```
+
+This builds the deck and shows every slide in Chrome, with all steps revealed as in a PDF. It reports, by slide, heading and line:
+
+- content that is taller than the slide's room for it;
+- text that is cut off at the slide's edge;
+- text that is hard to read on a plain background behind it;
+- errors the page reports, such as a component that fails.
+
+The check takes a few seconds and needs Chrome or Chromium; set `MDECK_CHROME` to its path if it is not found. It checks the deck in its own appearance. A slide with a problem it cannot measure, such as text on a photo, still needs a look in the preview.
+
+## Pictures of the slides
+
+```sh
+mdeck snapshot my-talk.md
+mdeck snapshot my-talk.md --slide 3,5-7 --dark
+```
+
+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`.
 
 ## Layouts, themes and palettes
 

package/docs/site/content/drawing.md

@@ -16,7 +16,7 @@ Press **D** in standalone slides or in the presenter view, or use the pen button
 
 **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.
+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; near a multiple of 15° (horizontal, vertical, 45° …) it snaps to that angle.
 
 **I** hides and shows what was drawn before, for example when a slide should look clean again. The toolbar has the same switch.
 

package/docs/site/content/more-content.md

@@ -81,6 +81,28 @@ This finding comes from our neighborhood survey.[^survey]
 
 The name inside the brackets connects the sentence to its source. Give each source a different name.
 
+If you keep your sources in Zotero or another reference manager, export them as a `.bib` file next to the deck and cite them by their keys. The slide shows a short citation and lists the full reference at its bottom; a slide with `<bibliography />` lists them all:
+
+```markdown
+---
+bibliography: refs.bib
+---
+# Results
+
+Gardens cool the street [@smith2020, p. 12].
+
+---
+# Sources
+
+<bibliography />
+```
+
+- `[@smith2020, p. 12]` adds a page, `[see @smith2020; @doe2019]` cites two works at once, and `@smith2020` in a sentence reads "Smith et al. (2020)".
+- `csl: vancouver` numbers the works instead; `harvard1` is built in too, and any style from the [Zotero style repository](https://www.zotero.org/styles) works as a `.csl` file next to the deck. Words such as "p." follow the deck's `lang`.
+- Besides `.bib`, a CSL-JSON file (`.json`) or a Typst Hayagriva file (`.yml`) works, and `bibliography:` takes a list of several.
+- A long list goes over two slides with `<bibliography part="1/2" />` and `<bibliography part="2/2" />`.
+- A key that is not in the file shows as `@key?`, and `mdeck check` names it.
+
 ## Add a QR code
 
 A QR code lets people open a link on their phones. Replace the address below with your own:

package/docs/site/content/sharing.md

@@ -20,6 +20,7 @@ Send `my-talk.html` by email. It opens in a **reader view**: an outline of all s
 
 - 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).
 - 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.
 - `-o` chooses the name: `mdeck send my-talk.md -o handout.html`.
 - The file keeps your theme and colours; readers can only switch between light and dark. To keep that fixed too, put `reader:` with `themes: false` in the settings at the top of your slide file.

package/docs/site/content/troubleshooting.md

@@ -61,7 +61,7 @@ For new slides, a settings block should begin with `:::meta` and end with `:::`.
 
 ## Text is missing or does not fit
 
-A slide has a fixed amount of space. Split a long explanation over two slides, shorten a paragraph, or try a simpler layout. The current checker does not automatically detect visual overflow; tell your assistant which slides overflow.
+A slide has a fixed amount of space. Split a long explanation over two slides, shorten a paragraph, or try a simpler layout. `mdeck check my-talk.md --render` lists the slides whose content does not fit, with the line each starts on.
 
 If you see an “unknown region” error, check that the layout supports the named area you used. For example, `left` and `right` work with `split`, but not with `title`.
 

package/docs/site/content/views.md

@@ -11,12 +11,14 @@ Every build and every preview contains all views. The address picks one with `?v
 | `?view=deck` | Standalone slides with drawing controls | Slides opened from the reader view or a built file |
 | `?view=presenter` | Current and next slide, notes and timer, and a button that opens the audience window | You, while presenting |
 | `?view=audience` | Slides without notes, with navigation synced to the presenter view | The projector |
-| `?view=reader` | The reader view: an outline, **Slides** and **Read** modes, a **Look** menu and a PDF | People you send the talk to |
+| `?view=reader` | The reader view: an outline, **Slides** and **Read** modes, light or dark, and a PDF | People you send the talk to |
+| `?view=follow` | The slide you are showing and your drawing, live; people can page back and return with **Back to live**, but never see a slide before you show it | People in the room, on their phone or laptop |
 
 Ways to switch between them:
 
 - The **Overview** link in the corner of the deck opens the reader view. Its outline is the overview of all slides.
 - **Present** in the reader view opens standalone slides at the current slide.
+- People in the room open the follow view with `<qrcode follow />` on a slide, with the **Follow the slides** link on the phones' answer page, or with the **Follow** address `mdeck run --network` prints. It works where their devices reach both the slides and your stage room: on the same network with `mdeck run --network`, or anywhere for a deck hosted with a `server` setting.
 - The presenter view's audience-window button opens the audience view in a new window. Navigation in either window updates the other, in the same browser or on a paired iPad: see [Draw on your slides](drawing.html#present-from-an-ipad).
 - The launch page of `mdeck run`, at the preview's plain address, offers Presenter, Audience and Reader. Its presenter and audience buttons belong together.
 - Fullscreen is a control inside a view (**F** or its fullscreen button). For a single screen, use the presenter view's slide-only layout.

package/examples/citations/refs.bib

@@ -0,0 +1,30 @@
+@article{sweller1988,
+  author  = {Sweller, John},
+  title   = {Cognitive Load During Problem Solving: Effects on Learning},
+  journal = {Cognitive Science},
+  year    = {1988},
+  volume  = {12},
+  number  = {2},
+  pages   = {257--285},
+  doi     = {10.1207/s15516709cog1202_4}
+}
+
+@article{roediger2006,
+  author  = {Roediger, Henry L. and Karpicke, Jeffrey D.},
+  title   = {Test-Enhanced Learning: Taking Memory Tests Improves Long-Term Retention},
+  journal = {Psychological Science},
+  year    = {2006},
+  volume  = {17},
+  number  = {3},
+  pages   = {249--255},
+  doi     = {10.1111/j.1467-9280.2006.01693.x}
+}
+
+@book{mayer2009,
+  author    = {Mayer, Richard E.},
+  title     = {Multimedia Learning},
+  edition   = {2},
+  publisher = {Cambridge University Press},
+  address   = {Cambridge},
+  year      = {2009}
+}

package/examples/citations/refs.yml

@@ -0,0 +1,21 @@
+# The same deck can draw on a Typst (Hayagriva) file as well.
+freeman2014:
+  type: Article
+  title: Active learning increases student performance in science, engineering, and mathematics
+  author:
+    - Freeman, Scott
+    - Eddy, Sarah L.
+    - McDonough, Miles
+    - Smith, Michelle K.
+    - Okoroafor, Nnadozie
+    - Jordt, Hannah
+    - Wenderoth, Mary Pat
+  date: 2014
+  page-range: 8410-8415
+  serial-number:
+    doi: 10.1073/pnas.1319030111
+  parent:
+    type: Periodical
+    title: Proceedings of the National Academy of Sciences
+    volume: 111
+    issue: 23

package/examples/citations/slides.md

@@ -0,0 +1,43 @@
+---
+theme: academic
+meta:
+  title: "What helps people learn"
+  author: "Tilman Schieber"
+  organization: "FHNW"
+bibliography: [refs.bib, refs.yml]
+csl: apa
+---
+
+---
+:::meta
+layout: title
+:::
+# What helps people learn
+## Citations from a reference file
+
+:::notes
+The references come from `refs.bib` (BibTeX, as Zotero exports it) and `refs.yml` (Hayagriva, Typst's format). Try `csl: vancouver` or `lang: de` in the deck settings.
+:::
+
+---
+# Less on the slide
+
+Working memory holds only a few things at once, so a slide that makes people search wastes it [@sweller1988].
+
+Words spoken alongside a picture beat the same words printed on it [@mayer2009, chap. 11].
+
+---
+# Ask, don't tell
+
+As @roediger2006 showed, recalling something fixes it better than reading it again.
+
+Lectures with active learning cut failure rates by about a third [@freeman2014; see also @roediger2006].
+
+:::notes
+Freeman et al. pooled 225 studies [-@freeman2014].
+:::
+
+---
+# References
+
+<bibliography />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeck",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "type": "module",
   "description": "Write slides as a plain text file, present them in the browser, share them as one HTML file or PDF.",
   "license": "MIT",
@@ -57,7 +57,11 @@
     "theme-images": "node tools/theme-images.mjs"
   },
   "dependencies": {
+    "@citation-js/core": "^0.9.0",
+    "@citation-js/plugin-bibtex": "^0.9.0",
+    "@citation-js/plugin-csl": "^0.9.0",
     "@preact/preset-vite": "^2.10.6",
+    "citeproc": "^2.4.63",
     "d3-cloud": "^1.2.9",
     "js-yaml": "^4.3.2",
     "katex": "^0.18.9",

package/skills/write-slides/SKILL.md

@@ -41,6 +41,8 @@ meta:
   author: "Name"
   organization: "FHNW"
   date: "2026-09-16"
+bibliography: refs.bib  # optional: .bib, CSL-JSON or Hayagriva; cite [@key, p. 3] or @key, list with <bibliography />
+csl: apa                # optional: apa, vancouver, harvard1 or a .csl file
 ---
 
 ---
@@ -128,10 +130,12 @@ The request is the message that invoked this skill: usually source material to t
 Save the deck as a `.md` file named after the topic (for example `enzyme-kinetics.md`), then run:
 
 ```sh
-mdeck check <deck>.md
+mdeck check <deck>.md --render
 ```
 
-Fix anything it reports. When you worked from source material, list what you left out or moved to notes, and anything you added that is not in the material. Finish by telling the user the two commands they will want next: `mdeck run <deck>.md` for the launch page (preview, presenting, editor, builds and checks), and `mdeck send <deck>.md` for a file to send around (a reader view with a PDF; notes are removed unless `--notes` is added).
+Fix anything it reports. `--render` builds the deck and shows every slide in Chrome with all steps revealed; it names each slide whose content does not fit, whose text is cut off at the edge or hard to read, with the line the slide starts on. Shorten or split those slides, or pick another layout, and check again. If Chrome is missing, run the check without `--render` and tell the user.
+
+To see slides yourself, if you can read pictures, run `mdeck snapshot <deck>.md --slide 3,5-7`: it saves PNG files to `.mdeck-snapshots/` beside the deck and prints their paths (`--dark` shows the dark appearance). Look at slides you were unsure about, such as diagrams, pictures and columns. When you worked from source material, list what you left out or moved to notes, and anything you added that is not in the material. Finish by telling the user the two commands they will want next: `mdeck run <deck>.md` for the launch page (preview, presenting, editor, builds and checks), and `mdeck send <deck>.md` for a file to send around (a reader view with a PDF; notes are removed unless `--notes` is added).
 
 ## 5. A new look: themes and palettes