mdeck 2.3.0

package/docs/site/build.js

@@ -0,0 +1,148 @@
+import { readFile, writeFile, mkdir, copyFile, cp } from 'node:fs/promises'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { Marked, Renderer } from 'marked'
+import Prism from 'prismjs'
+import 'prismjs/components/prism-markdown.js'
+import 'prismjs/components/prism-yaml.js'
+import 'prismjs/components/prism-jsx.js'
+import 'prismjs/components/prism-bash.js'
+import { pages } from './pages.js'
+import { frameworkRoot as projectRoot } from '../../src/paths.js'
+import { loadRegistry, manifestsOf } from '../../src/extensions/discover.js'
+import { palettesFor } from '../../src/extensions/tokens.js'
+import { createRequire } from 'node:module'
+
+const REPO = 'https://github.com/tilman-schieber/mdeck'
+const LINKS = [['Repository', REPO], ['Releases', `${REPO}/releases`], ['Package', 'https://www.npmjs.com/package/mdeck'], ['Issues', `${REPO}/issues`]]
+const version = createRequire(import.meta.url)('../../package.json').version
+const projectLinks = () => LINKS.map(([label, href]) => `<a href="${href}" rel="noopener">${label}</a>`).join('')
+import { parseSlides } from '../../src/core/parseSlides.js'
+import { readFileSync, existsSync } from 'node:fs'
+
+export const docsRoot = dirname(fileURLToPath(import.meta.url))
+const exec = promisify(execFile)
+export const escape = value => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+const plain = html => html.replace(/<[^>]*>/g, '').replace(/&(?:amp|lt|gt|quot|#39);/g, value => ({ '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'" })[value])
+
+function navigation(current) {
+  const groups = [...new Set(pages.map(p => p.group))]
+  return groups.map(group => {
+    const links = pages.filter(p => p.group === group).map(p => `<a href="${p.slug}.html"${p.slug === current.slug ? ' aria-current="page"' : ''}>${escape(p.title)}</a>`).join('')
+    if (group === 'Advanced customization') return `<details class="advanced-nav"${current.group === group ? ' open' : ''}><summary>${group}</summary><div>${links}</div></details>`
+    return `<div class="nav-group"><p>${group}</p>${links}</div>`
+  }).join('')
+}
+
+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) {
+  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('')
+}
+
+function preview(page) {
+  if (!page.preview) return ''
+  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>
+  </figure>`
+}
+
+// <!-- theme-sheets light --> (or dark) becomes one tab per theme with a
+// contact sheet of its chapter slide in every palette (tools/theme-images.mjs).
+function themeSheets(appearance) {
+  const registry = loadRegistry(exampleFiles['first-talk'])
+  const palettes = manifestsOf(registry, 'palette')
+  const themes = Object.values(manifestsOf(registry, 'theme'))
+    .filter(theme => palettesFor(theme, palettes).length > 1 && existsSync(resolve(docsRoot, `images/themes/${theme.id}-${appearance}.webp`)))
+  const id = theme => `sheet-${appearance}-${theme.id}`
+  const tabs = themes.map((theme, i) => `<button type="button" role="tab" id="${id(theme)}-tab" aria-controls="${id(theme)}" aria-selected="${i === 0}">${escape(theme.title)}</button>`).join('')
+  const panels = themes.map(theme => {
+    const src = `images/themes/${theme.id}-${appearance}.webp`
+    return `<div class="theme-sheet" role="tabpanel" id="${id(theme)}" aria-labelledby="${id(theme)}-tab"><a href="${src}"><img src="${src}" alt="The ${escape(theme.title)} theme's chapter slide in every palette, ${appearance}" loading="lazy"></a></div>`
+  }).join('')
+  return `<div class="theme-sheets" data-tabs><div class="theme-tabs" role="tablist" aria-label="Theme, ${appearance}">${tabs}</div>${panels}</div>`
+}
+
+export function renderPage(page, markdown) {
+  const headings = [], used = new Map()
+  let title = page.title
+  const firstHeading = markdown.match(/^# (.+)\r?$/m)
+  if (firstHeading) { title = firstHeading[1]; markdown = markdown.replace(firstHeading[0], '') }
+  const renderer = {
+    heading({ tokens, depth: level }) {
+      const text = this.parser.parseInline(tokens)
+      const base = plain(text).toLowerCase().replace(/[^a-z0-9\s-]/g, '').trim().replace(/\s+/g, '-') || 'section'
+      const count = used.get(base) ?? 0
+      used.set(base, count + 1)
+      const id = base + (count ? `-${count + 1}` : '')
+      if (level === 2) headings.push({ id, text: plain(text) })
+      return `<h${level} id="${id}">${text}<a class="heading-link" href="#${id}" aria-label="Link to ${escape(plain(text))}">#</a></h${level}>\n`
+    },
+    code({ text: code, lang: info }) {
+      const language = (info ?? '').split(/\s/)[0]
+      const grammar = Prism.languages[{ sh: 'bash', html: 'markup', text: 'plain' }[language] ?? language]
+      const html = grammar ? Prism.highlight(code, grammar, language) : escape(code)
+      return `<figure class="code-example"><figcaption><span>${{ sh: 'In your terminal', prompt: 'Ask your assistant' }[language] ?? 'Example'}</span><button type="button" data-copy aria-label="Copy example">Copy</button></figcaption><pre><code>${html}</code></pre></figure>\n`
+    },
+    table(token) { return `<div class="table-scroll" tabindex="0" role="region" aria-label="Reference table">${Renderer.prototype.table.call(this, token)}</div>` },
+    link({ href, title: linkTitle, tokens }) {
+      const text = this.parser.parseInline(tokens)
+      const aliases = { 'layouts.md': 'custom-layouts.html', 'extensions.md': 'extensions.html', 'themes.md': 'theme-authoring.html', 'palettes.md': 'theme-authoring.html', '../../examples/custom-layouts/slides.md': 'downloads/comparison.md' }
+      href = href.replace(/^extensions\.md#/, 'extensions.html#')
+      href = aliases[href] ?? href
+      return `<a href="${escape(href)}"${linkTitle ? ` title="${escape(linkTitle)}"` : ''}>${text}</a>`
+    },
+  }
+  const parser = new Marked({ renderer })
+  const article = parser.parse(markdown).replace('<!-- preview -->', preview(page))
+    .replace(/<!-- theme-sheets (light|dark) -->/g, (_, appearance) => themeSheets(appearance))
+  const index = pages.indexOf(page)
+  const previous = pages[index - 1], next = pages[index + 1]
+  const footerLinks = `${previous ? `<a href="${previous.slug}.html"><small>Previous guide</small>${escape(previous.title)}</a>` : '<span></span>'}${next ? `<a href="${next.slug}.html"><small>Next guide</small>${escape(next.title)}</a>` : ''}`
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="${escape(page.description)}"><title>${escape(page.title)} · mdeck guide</title><link rel="icon" href="assets/favicon.svg" type="image/svg+xml"><link rel="stylesheet" href="assets/site.css?v=${escape(version)}"><script src="assets/site.js?v=${escape(version)}" defer></script></head>
+<body${page.slug === 'index' ? ' class="welcome"' : ''}>
+<a class="skip-link" href="#main">Skip to the guide</a>
+<header class="site-header"><a class="brand" href="index.html" aria-label="mdeck documentation home"><img src="assets/favicon.svg" alt="" width="26" height="26"><span>mdeck</span><span class="brand-guide">Guide</span></a>
+<div class="header-tools"><div class="search-box" role="search"><label for="search" class="sr-only">Search the guides</label><input id="search" type="search" placeholder="Search the guides" autocomplete="off" aria-controls="search-results" aria-expanded="false"><kbd aria-hidden="true">/</kbd><div id="search-results" hidden></div><span id="search-status" class="sr-only" aria-live="polite"></span></div>
+<a class="repo-link" href="${REPO}" rel="noopener"><img src="assets/github-logo.svg" alt="" width="20" height="20">GitHub</a></div></header>
+<div class="site-layout"><details class="nav-shell" open><summary>Browse the guides</summary><nav aria-label="Documentation">${navigation(page)}<a class="nav-help" href="commands.html">Open these docs: <code>mdeck docs</code></a><div class="nav-group nav-project"><p>mdeck ${escape(version)} on GitHub</p>${projectLinks()}</div></nav></details>
+<main id="main" tabindex="-1"><article><header class="article-header"><p class="breadcrumb">${escape(page.group)}</p><h1>${escape(title)}</h1>${page.group === 'Advanced customization' ? '<p class="advanced-notice">This section is for people comfortable with code. You can make and present slides without it.</p>' : ''}</header>${article}</article><nav class="page-navigation" aria-label="Previous and next guide">${footerLinks}</nav><footer class="article-footer"><span>mdeck ${escape(version)}</span><span class="footer-links">${projectLinks()}</span></footer></main>
+<aside class="page-outline" aria-label="On this page"><p>On this page</p>${headings.map(h => `<a href="#${h.id}">${escape(h.text)}</a>`).join('')}</aside></div></body></html>`
+  return { html, headings, search: { title: page.title, href: `${page.slug}.html`, description: page.description, text: plain(article).replace(/\s+/g, ' ').trim() } }
+}
+
+export async function buildDocs({ outDir = resolve(docsRoot, 'dist'), examples = true } = {}) {
+  await mkdir(resolve(outDir, 'assets'), { recursive: true })
+  await mkdir(resolve(outDir, 'downloads'), { recursive: true })
+  const search = []
+  for (const page of pages) {
+    const file = page.source ? resolve(docsRoot, page.source) : resolve(docsRoot, 'content', page.file)
+    const { html, search: entry } = renderPage(page, await readFile(file, 'utf8'))
+    await writeFile(resolve(outDir, `${page.slug}.html`), html)
+    search.push(entry)
+  }
+  for (const file of ['site.css', 'site.js', 'favicon.svg', 'github-logo.svg']) await copyFile(resolve(docsRoot, 'assets', file), resolve(outDir, 'assets', file))
+  await cp(resolve(docsRoot, 'images'), resolve(outDir, 'images'), { recursive: true })
+  await writeFile(resolve(outDir, 'search.json'), JSON.stringify(search))
+  await copyFile(resolve(projectRoot, 'examples/custom-layouts/slides.md'), resolve(outDir, 'downloads/comparison.md'))
+  await copyFile(resolve(docsRoot, 'examples/first-talk.md'), resolve(outDir, 'downloads/first-talk.md'))
+  if (examples) {
+    for (const [name, file] of Object.entries(exampleFiles)) {
+      await exec(process.execPath, [resolve(projectRoot, 'bin/mdeck.js'), 'build', file, '--single-file', '-o', resolve(outDir, 'examples', `${name}.html`)], { cwd: projectRoot, maxBuffer: 4 * 1024 * 1024 })
+    }
+  }
+  return outDir
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  console.log(`Documentation built: ${await buildDocs()}`)
+}

package/docs/site/content/appearance.md

@@ -0,0 +1,203 @@
+# Change the look
+
+A **theme** chooses the fonts and the style of the slides. A **palette** chooses the colours, in a light and a dark version. You can change either without rewriting your slides.
+
+Ask your assistant by name or by description:
+
+```prompt
+Use the aurora theme, dark. Or suggest a look that suits a talk for
+a design conference.
+```
+
+The settings it changes are the ones described below. To try looks before deciding, use the presenter view (see “Try a look before saving it”).
+
+## Choose a theme
+
+Put the theme name under `theme` in the settings at the very top of your file:
+
+```yaml
+---
+theme: neue
+---
+```
+
+If you already have a settings block there, change the existing lines rather than adding a second block.
+
+| Name to use | What it looks like |
+|---|---|
+| `neue` | Swiss style: large type, clear lines, red on white |
+| `aurora` | Northern lights: curtains of light, night-sky chapters and glass |
+| `duet` | Two voices: two accent colours that take turns, slab headings |
+| `editorial` | A magazine spread: serif headlines, drop caps, pull quotes |
+| `fhnw` | The FHNW visual identity |
+| `terminal` | A terminal session: headings typed at a prompt, a blinking cursor, a status bar |
+| `academic` | A lecture: compact slides, theorem and definition boxes, tables like in a paper |
+| `sketch` | A sketchbook: handwriting, marker scribbles, sticky notes; a chalkboard in the dark |
+
+Each theme comes with colours that suit it, so you do not have to choose any.
+
+## See the themes
+
+Each theme in its own colours, on the title slide of the tour example. Click a picture to see it larger.
+
+### Neue
+
+[![The tour's title slide in the Neue theme](images/themes/neue.webp)](images/themes/neue.webp)
+
+Default colours: `swiss`.
+
+### Aurora
+
+[![The tour's title slide in the Aurora theme](images/themes/aurora.webp)](images/themes/aurora.webp)
+
+Default colours: `neon`.
+
+### Duet
+
+[![The tour's title slide in the Duet theme](images/themes/duet.webp)](images/themes/duet.webp)
+
+Default colours: `cobalt`.
+
+### Editorial
+
+[![The tour's title slide in the Editorial theme](images/themes/editorial.webp)](images/themes/editorial.webp)
+
+Default colours: `terra`.
+
+### FHNW
+
+[![The tour's title slide in the FHNW theme](images/themes/fhnw.webp)](images/themes/fhnw.webp)
+
+Default colours: its own FHNW colours.
+
+### Terminal
+
+[![The tour's title slide in the Terminal theme](images/themes/terminal.webp)](images/themes/terminal.webp)
+
+Default colours: `phosphor`, dark.
+
+### Academic
+
+[![The tour's title slide in the Academic theme](images/themes/academic.webp)](images/themes/academic.webp)
+
+Default colours: `nordic`.
+
+### Sketch
+
+[![The tour's title slide in the Sketch theme](images/themes/sketch.webp)](images/themes/sketch.webp)
+
+Default colours: `pastel`.
+
+## Choose colours
+
+To use other colours, set `palette` to one of these:
+
+| Name to use | Colours |
+|---|---|
+| `lagoon` | Teal on warm stone |
+| `swiss` | White, black and signal red (neue's own) |
+| `cobalt` | Strong ultramarine on white |
+| `nordic` | Ice grey, deep navy and a cool steel blue |
+| `graphite` | Black and white with a steel-blue accent |
+| `terra` | Cream, deep navy and brick red |
+| `forest` | Deep green with moss and ochre |
+| `ember` | Sand and espresso with orange |
+| `neon` | Violet and magenta, loud |
+| `phosphor` | Green on black, like an old terminal screen |
+| `pastel` | Soft pastels, mauve and peach (in the style of Catppuccin) |
+
+```yaml
+---
+theme: neue
+palette: terra
+---
+```
+
+The FHNW theme always uses the FHNW colours.
+
+## Light or dark
+
+Every palette has a light and a dark version. Choose dark for a dark lecture hall, light for a bright room:
+
+```yaml
+---
+theme: neue
+palette: terra
+appearance: dark
+---
+```
+
+Some slides use the other version on purpose: neue's statement slides are dark in a light talk and light in a dark one.
+
+## Every theme in every palette
+
+The first chapter slide of the tour in each palette a theme offers. Choose a theme above the pictures; click a sheet to see it larger. The FHNW theme has only its own colours, so it is not shown here.
+
+Some themes turn their chapter slides around on purpose: aurora's are a night sky in a light talk, and light in a dark one.
+
+### Light
+
+<!-- theme-sheets light -->
+
+### Dark
+
+<!-- theme-sheets dark -->
+
+## Try a look before saving it
+
+Open the launch page and choose **Presenter view**:
+
+```sh
+mdeck run my-talk.md
+```
+
+Its theme, palette and light or dark controls, under the notes, let you try other looks (fold them away with the arrow beside them). These changes are a preview: they do not save back to your text file. Once you find a look you like, put its settings in the file and save.
+
+## More themes from other people
+
+The theme repository has themes and palettes others made. `mdeck themes search` lists them, and `mdeck themes install <pack> my-talk.md` puts one beside your slides; see [Install or share a theme](theme-repository.html).
+
+## Add your name and organization
+
+```yaml
+---
+theme: neue
+meta:
+  title: "A place to grow"
+  author: "Alex Morgan"
+  organization: "The garden team"
+  date: "12 June 2026"
+---
+```
+
+The text on the title slide still comes from the heading you write on that slide. The settings above supply information for the slide's header and footer.
+
+You can also add `logo: ./img/logo.png` inside the `meta` group.
+
+## Control headers and page numbers
+
+These settings go together under `show`, in the deck settings:
+
+```yaml
+show:
+  organization: none
+  numbers: all
+```
+
+| Setting | Choices | Usual behavior |
+|---|---|---|
+| `show.organization` | `title`, `all`, `none` | Organization appears on the title slide |
+| `show.author` | `title`, `all`, `none` | Author and date appear on the title slide |
+| `show.numbers` | `slides`, `all`, `none` | Numbers appear after the title slide |
+| `show.sections` | `all`, `none` | Section labels appear when provided |
+
+## Change the slide shape
+
+The usual shape is widescreen, with a width of 1920 and height of 1080. For a classic 4:3 shape, set:
+
+```yaml
+width: 1920
+height: 1440
+```
+
+Check your slides after changing their shape. A layout that fit before may need fewer words or a different picture crop.

package/docs/site/content/audience.md

@@ -0,0 +1,178 @@
+# Ask your audience
+
+A slide can ask a question that people answer on their phones, with the results appearing on the slide as they come in.
+
+Your assistant can add these for you. Say what you want to find out and where in the talk:
+
+```prompt
+Before the chapter on methods, ask which of the three methods people
+have used, and end with a slide for open questions. Show the QR code
+once at the start.
+```
+
+The rest of this page shows what it writes, and how to run the questions in a real room.
+
+## Add a poll
+
+```markdown
+---
+# Where do we eat?
+
+<poll room="lunch" options="Mensa|Thai|Pizza|Salad" />
+```
+
+The slide shows one bar per option, the number of answers, a QR code and a short link. Scanning the code opens a small answer page on the phone with one button per option. Each phone has one vote and can change it; the bars follow the latest answer.
+
+Every poll in a presentation shows the same code, so people scan once. Their phones then follow along: when you reach a slide with a poll, its buttons appear on every phone; between polls, the phones say that the next question will appear there. You can show the code at the start of the talk, or on the first poll.
+
+| Setting | Meaning |
+|---|---|
+| `room` | A short name for this question, different for each poll in the deck. Letters, digits, hyphens and underscores. |
+| `answer` | Optional: the right answer, written exactly like the option. A button with a tick then appears under the bars; tapping it outlines the right answer, its bar and its number in green, and tapping again hides it. The audience window shows it too. |
+| `options` | The answers, separated by `\|` |
+| `question` | Optional question text. Without it, phones show the slide's heading. |
+| `qr` | `false` leaves out the QR code, when an earlier slide showed it with `<qrcode join />`. |
+
+With `lang: de` in the settings, the slide and the phones show German words, such as “Scannen und abstimmen”. The phones use the presentation's colours and fonts; if you pick another theme or palette in the presenter view, the phones change with it.
+
+## Other kinds of questions
+
+Besides a poll, three more kinds work the same way: one line on a slide, answered on the phones.
+
+```markdown
+<scale room="pace" min="1" max="5" low="Too slow" high="Too fast" />
+<wordcloud room="mood" placeholder="One word" />
+<question room="ask" placeholder="Your question" />
+```
+
+| Tag | Phones show | The slide shows |
+|---|---|---|
+| `<scale>` | The numbers from `min` to `max` (1 to 5 unless set, at most 11 steps), with `low` and `high` as labels at the ends | How many chose each number, and the average. Each phone's latest answer counts |
+| `<wordcloud>` | A short text field | A cloud of every answer, packed around the middle, larger the more often it came in and some upright. Capitals and extra spaces do not matter. People may send several. `height` sets its height (520). Colours come from the palette; `--cloud-1` to `--cloud-6` override them |
+| `<question>` | A text field | The newest answers as cards, eight unless `limit` says otherwise. People may send several |
+
+All of them take `room`, `question` and `qr` like a poll, and `placeholder` for the text fields.
+
+## Show the code once
+
+Each question shows the QR code unless you say otherwise. To invite everybody once, at the start, put the code on a slide of its own and leave it out of the questions:
+
+```markdown
+---
+# Take out your phone.
+
+<qrcode join />
+
+---
+# How do you make slides today?
+
+<poll room="tools" options="PowerPoint|Keynote|Markdown" qr="false" />
+```
+
+`<qrcode join />` shows the presentation's join code large, with the link below it. Phones that scanned it follow along to every question. With `qr="false"`, a question leaves out its own code. Leave the join slide up for a while, or come back to it, for people who arrive late. `size` sets the size of the code on the join slide.
+
+The code is drawn in the slide's colours, so it fits the theme; phone cameras also read light codes on dark slides.
+
+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
+
+The phones never load your slides. A small **server** connects your screen and the phones: your screen tells it which poll is showing and what the phones should display, and the server shows that on its own answer page, at an address like `example.org/482113`. The six digits are the presentation's session code; they stay the same for the whole talk.
+
+So you present from your own computer with `mdeck run`, always with the slides as they are right now, and nothing needs to be uploaded. Only the server has to be reachable by the phones.
+
+## Try it on your computer
+
+`mdeck run` has a server built in:
+
+```sh
+mdeck run my-talk.md --network
+```
+
+`--network` makes it reachable from phones and tablets in the same network, and the QR code then points at your computer. Without `--network`, the slide says so and offers a link to try the answer page in another browser tab on your computer. The launch page shows the join link and the session code too.
+
+Some networks, often large Wi-Fi networks at universities, do not let devices reach each other. If phones cannot open the page, connect your laptop and the phones to a phone hotspot, or use a server on the internet (below).
+
+## Use it in a real session
+
+For a lecture hall, run your own server once on a web server; it can serve all your presentations, and it also lets an iPad present from any network (see [Draw on your slides](drawing.html#present-from-an-ipad)). On that machine, install mdeck and start it:
+
+```sh
+MDECK_SERVER_KEY=choose-a-secret mdeck server
+```
+
+It listens on `127.0.0.1:8787`. Give it a host name of its own, such as `rooms.example.org`, and make your web server pass everything on that name to it, for example with nginx:
+
+```nginx
+# in the http block
+map $http_upgrade $connection_upgrade { default upgrade; '' ''; }
+
+server {
+  server_name rooms.example.org;
+  # your usual listen and certificate lines here
+
+  location / {
+    proxy_pass http://127.0.0.1:8787;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_buffering off;
+    proxy_read_timeout 1h;
+  }
+}
+```
+
+The slides and phones keep a connection open to receive answers live, which is why buffering is off and the timeout long. The `Upgrade` lines let WebSocket connections through, which presenting from an iPad needs; polls alone work without them. `X-Forwarded-For` lets the server limit each phone, not the web server as a whole. A server on a path of a shared host name, such as `example.org/rooms/`, works for polls too, but presenting from an iPad needs a name of its own.
+
+`MDECK_SERVER_KEY` is required for presenting from an iPad: a server without a key does not offer it, and a laptop that does not know the key cannot connect. The server only passes requests along: it keeps nothing of your slides, and a presentation shared through it disappears when the laptop disconnects or the server restarts.
+
+To keep the server running and start it with the machine, a systemd service works well. Put the key in a file only root can read, for example `/etc/mdeck-server.env` with the line `MDECK_SERVER_KEY=choose-a-secret`, and create `/etc/systemd/system/mdeck-server.service`:
+
+```ini
+[Unit]
+Description=mdeck server
+After=network.target
+
+[Service]
+EnvironmentFile=/etc/mdeck-server.env
+ExecStart=/usr/local/bin/mdeck server --port 8787
+User=www-data
+Restart=on-failure
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Adjust `ExecStart` to where `which mdeck` points; if Node is installed in a home folder, for example with nvm, also remove `ProtectHome=true`. Then run `sudo systemctl enable --now mdeck-server`. `journalctl -u mdeck-server` shows its log. After updating mdeck, `sudo systemctl restart mdeck-server`; rooms start empty again.
+
+Then tell the presentation where the server is:
+
+```yaml
+---
+server: https://rooms.example.org
+---
+```
+
+To keep the address out of the deck, leave the setting out and set `MDECK_SERVER=https://rooms.example.org` in your shell instead; `mdeck run --server` then finds it. A built or sent presentation reads the address from the deck only, because it has to carry it to wherever it is opened.
+
+`MDECK_SERVER_KEY` is the server’s master key. `mdeck run` keeps it on your computer and lets your local browser, or an iPad with a revocable pairing token, move the phones along and reset polls for this deck. Pairing QR codes never include the master key. Start `mdeck run` with the same key (`MDECK_SERVER_KEY=choose-a-secret mdeck run my-talk.md`), and the launch page checks the server, shows the join link and opens the presenter view. Paired devices remember only their token, scoped to this presentation; it never appears in the address bar or in the slide file. A hosted presenter can still unlock the server by opening the presenter view once with `?serverkey=…` in its address. That browser remembers the master key. Without permission to control the server, phones wait. The presenter view says whether the phones follow it, and if not, why.
+
+The presenter's screen repeats the current poll every few seconds, so phones that join late, or a server that restarted, catch up. While a presenter view is open, other windows of the presentation in the same browser leave the phones alone. If the presentation is open on several screens, even in other browsers, the phones follow the one where the slides were changed last; just opening it elsewhere does not take them away. A presenter view that has lost the phones says so, and changing the slide there takes them back.
+
+Two presentations with the same title share a session code. Give one of them `session: id:`, or set the digits yourself with `session: code:`.
+
+## What is stored
+
+Answers are anonymous. Each phone gets a random number so it can change its vote; nothing else identifies it. The server keeps answers in memory only. It forgets a room after twelve hours without visitors and everything when it restarts. Each phone can send a limited number of answers in a short time.
+
+## In a PDF or a shared file
+
+A PDF, a file made with `mdeck send` and a folder hosted without a poll server keep your questions as a record of the talk: each shows its question and options, with a note that it was answered live, and no join code. If the deck's `server` still answers when the file is made or opened, the results it holds appear instead. Printed slides never show the join code or the presenter's buttons.
+
+## Make your own activity
+
+Polls, scales, word clouds and questions are ordinary components. The [interactive content](components.html#audience-interaction) guide shows how to write your own, such as a quiz, or ask your assistant to write one.