mdeck 2.3.0

package/docs/site/pages.js

@@ -0,0 +1,27 @@
+export const pages = [
+  { slug: 'index', title: 'Welcome to mdeck', group: 'Start here', file: 'welcome.md', description: 'Turn your existing slides, documents and notes into a deck with an AI assistant, then present and share it.', preview: 'first-talk' },
+  { slug: 'getting-started', title: 'Make your first presentation', group: 'Start here', file: 'getting-started.md', description: 'Set up mdeck and your AI assistant, hand over your material, and open the deck it makes.' },
+  { slug: 'claude-skill', title: 'Work with an AI assistant', group: 'Start here', source: '../reference/claude-skill.md', description: 'Set up Claude Code, Codex, Cursor, Copilot or Gemini, turn PowerPoint, PDF, Word or notes into a deck, and change it by asking.' },
+  { slug: 'writing', title: 'Read and adjust your slides', group: 'Make your presentation', file: 'writing.md', description: 'The simple marks in a slide file, so you can read what your assistant wrote and fix small things.' },
+  { slug: 'editing', title: 'Edit slides in your browser', group: 'Make your presentation', file: 'editing.md', description: 'Change text, layouts, colors and themes with a visual editor that saves to your slide file.' },
+  { slug: 'layouts', title: 'Choose a slide layout', group: 'Make your presentation', file: 'layouts.md', description: 'Choose a title slide, a big statement, a picture, or two columns.', preview: 'first-talk' },
+  { slug: 'pictures-and-video', title: 'Add pictures and video', group: 'Make your presentation', file: 'media.md', description: 'Put an image or a video into your talk and keep its files together.' },
+  { slug: 'appearance', title: 'Change the look', group: 'Make your presentation', file: 'appearance.md', description: 'Choose fonts and colors with themes and palettes.' },
+  { slug: 'theme-repository', title: 'Install or share a theme', group: 'Make your presentation', file: 'theme-repository.md', description: 'Themes and palettes other people made, installed with one command, and how to share your own.' },
+  { slug: 'notes-and-presenting', title: 'Add notes and present', group: 'Present and share', file: 'presenting.md', description: 'See your notes, reveal points one at a time, and open the audience screen.' },
+  { slug: 'audience', title: 'Ask your audience', group: 'Present and share', file: 'audience.md', description: 'Polls that people answer on their phones, with live results on the slide.' },
+  { slug: 'drawing', title: 'Draw on your slides', group: 'Present and share', file: 'drawing.md', description: 'Mark up slides with a pen or an iPad, live or ahead of time, and keep the drawings with the talk.' },
+  { slug: 'sharing', title: 'Send, host or print your slides', group: 'Present and share', file: 'sharing.md', description: 'Make a shareable folder, a single file, or a PDF.' },
+  { slug: 'more-content', title: 'Tables, tips, and more', group: 'Keep learning', file: 'more-content.md', description: 'Add tables, helpful callouts, QR codes, formulas, and code examples.' },
+  { slug: 'reusable-layouts', title: 'Use a reusable layout', group: 'Keep learning', file: 'reusable-layouts.md', description: 'Use a layout someone has made for you, including the comparison example.', preview: 'custom-layouts' },
+  { slug: 'commands', title: 'Command guide', group: 'Help and reference', file: 'commands.md', description: 'What each mdeck command does and when to use it.' },
+  { slug: 'views', title: 'Views, commands and servers', group: 'Help and reference', file: 'views.md', description: 'Which view is which, how to switch, and what needs a server.' },
+  { slug: 'troubleshooting', title: 'When something goes wrong', group: 'Help and reference', file: 'troubleshooting.md', description: 'Find a missing picture, fix a typing mistake, or recover a command that will not run.' },
+  { slug: 'custom-layouts', title: 'Create a custom layout', group: 'Advanced customization', source: '../reference/layouts.md', description: 'The files behind a layout, its content areas, and its settings, as an assistant or a JavaScript author writes them.' },
+  { slug: 'components', title: 'Create interactive content', group: 'Advanced customization', file: 'components.md', description: 'Interactive slide content as Preact components, written by your assistant or by hand.' },
+  { slug: 'theme-authoring', title: 'Create a theme or palette', group: 'Advanced customization', file: 'theme-authoring.md', description: 'The files behind a visual identity for a whole deck, as an assistant or a CSS author writes them.' },
+  { slug: 'extensions', title: 'Extension manifests', group: 'Advanced customization', source: '../reference/extensions.md', description: 'The one manifest format shared by templates, themes and palettes.' },
+  { slug: 'source-model', title: 'Build tools around mdeck', group: 'Advanced customization', source: '../reference/structured-slides.md', description: 'The source-preserving document model and editing helpers for tool authors.' },
+]
+
+export const pageFor = slug => pages.find(page => page.slug === slug)

package/docs/site/server.js

@@ -0,0 +1,58 @@
+import { createServer } from 'node:http'
+import { readFile, mkdtemp, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { resolve, relative, extname, isAbsolute } from 'node:path'
+import { spawn } from 'node:child_process'
+import { buildDocs } from './build.js'
+import { pageFor } from './pages.js'
+
+const MIME = { '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.webp': 'image/webp', '.png': 'image/png', '.md': 'text/plain; charset=utf-8' }
+
+export function docsHandler(root) {
+  return async (request, response) => {
+    if (!['GET', 'HEAD'].includes(request.method)) { response.writeHead(405, { Allow: 'GET, HEAD' }); response.end(); return }
+    try {
+      const pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname)
+      const file = resolve(root, '.' + (pathname === '/' ? '/index.html' : pathname))
+      const rel = relative(root, file)
+      if (rel.startsWith('..') || isAbsolute(rel) || !(await stat(file)).isFile()) throw new Error('Not found')
+      const content = await readFile(file)
+      response.writeHead(200, { 'Content-Type': MIME[extname(file)] ?? 'application/octet-stream', 'Content-Length': content.length, 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'no-cache' })
+      response.end(request.method === 'HEAD' ? undefined : content)
+    } catch {
+      response.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' })
+      response.end(request.method === 'HEAD' ? undefined : '<!doctype html><html lang="en"><title>Guide not found</title><h1>That guide could not be found.</h1><p><a href="/">Go back to the mdeck guide.</a></p></html>')
+    }
+  }
+}
+
+export async function startDocs({ page = 'index', port = 4174, open = true } = {}) {
+  if (!pageFor(page)) throw new Error(`There is no guide named "${page}". Try "getting-started", "sharing", or "commands".`)
+  const outDir = await mkdtemp(resolve(tmpdir(), 'mdeck-docs-'))
+  let server
+  try {
+    await buildDocs({ outDir })
+    server = createServer(docsHandler(outDir))
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', () => { server.removeListener('error', reject); resolve() }) })
+        break
+      } catch (error) {
+        if (error.code !== 'EADDRINUSE' || attempt >= 20 || port >= 65535) throw error
+        port++
+      }
+    }
+    const url = `http://127.0.0.1:${server.address().port}/${page === 'index' ? '' : `${page}.html`}`
+    if (open) {
+      const [command, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]]
+      const opener = spawn(command, args, { stdio: 'ignore' })
+      opener.on('error', () => console.log(`Open ${url} in your browser.`))
+      opener.unref()
+    }
+    return { server, url, outDir, async close() { await new Promise(resolve => server.close(resolve)); await rm(outDir, { recursive: true, force: true }) } }
+  } catch (error) {
+    server?.close()
+    await rm(outDir, { recursive: true, force: true })
+    throw error
+  }
+}

package/examples/custom-layouts/extensions/comparison/extension.toml

@@ -0,0 +1,35 @@
+schema = 1
+kind = "layout"
+id = "comparison"
+title = "Side-by-side comparison"
+description = "Two options next to each other, with one of them optionally highlighted."
+
+# layout.jsx, styles.css and starter.md are picked up from this folder by default.
+
+[regions.body]
+description = "Shared heading and introduction"
+
+[regions.left]
+required = true
+description = "First option"
+
+[regions.right]
+required = true
+description = "Second option"
+
+[properties.ratio]
+type = "array"
+description = "Relative widths of the two options"
+minItems = 2
+maxItems = 2
+default = [1, 1]
+
+[properties.ratio.items]
+type = "number"
+minimum = 0.01
+
+[properties.emphasis]
+type = "string"
+description = "Which option gets the highlighted border"
+enum = ["none", "left", "right"]
+default = "none"

package/examples/custom-layouts/extensions/comparison/layout.jsx

@@ -0,0 +1,15 @@
+import { h } from 'preact'
+import { MarkdownRegion } from 'mdeck/layout'
+
+export default function Comparison({ regions, props }) {
+  return <div class="slide-body comparison-body">
+    <MarkdownRegion region={regions.body} />
+    <div class="comparison-options" style={{ gridTemplateColumns: `${props.ratio[0]}fr ${props.ratio[1]}fr` }}>
+      {['left', 'right'].map(name => <MarkdownRegion
+        key={name}
+        region={regions[name]}
+        class={`comparison-option${props.emphasis === name ? ' is-emphasized' : ''}`}
+      />)}
+    </div>
+  </div>
+}

package/examples/custom-layouts/extensions/comparison/starter.md

@@ -0,0 +1,17 @@
+:::meta
+layout: comparison
+props:
+  ratio: [1, 1]
+  emphasis: none
+:::
+# Compare two options
+
+:::slot left
+## First option
+Describe it here.
+:::
+
+:::slot right
+## Second option
+Describe it here.
+:::

package/examples/custom-layouts/extensions/comparison/styles.css

@@ -0,0 +1,4 @@
+.slide--comparison .comparison-body { gap: 40px; }
+.slide--comparison .comparison-options { display: grid; gap: 40px; min-height: 0; }
+.slide--comparison .comparison-option { min-width: 0; padding: 28px; border: 2px solid var(--rule); }
+.slide--comparison .comparison-option.is-emphasized { border-color: var(--accent); }

package/examples/custom-layouts/slides.md

@@ -0,0 +1,60 @@
+---
+theme: terminal
+meta:
+  title: Deck-local layouts
+---
+
+---
+:::meta
+layout: comparison
+id: deployment-options
+props:
+  ratio: [2, 3]
+  emphasis: right
+:::
+# Deployment options
+
+:::slot left
+## Directory bundle
+
+- Separate media files
+- Suitable for large videos
+:::
+
+:::slot right
+## Single HTML file
+
+:::tip
+Useful when transferring one file is operationally important.
+:::
+
+- All local assets embedded
+- Larger video payloads
+:::
+
+:::notes
+This layout is loaded from extensions/comparison beside this deck.
+:::
+
+---
+:::meta
+layout: split
+id: built-in-regions
+props:
+  ratio: [1, 2]
+:::
+# Built-in layouts use the same region model
+
+:::slot left
+```js
+const template = 'comparison'
+```
+:::
+
+:::slot right
+:::steps
+- Define a manifest.
+- Write a Preact layout.
+- Use it from Markdown.
+:::
+:::

package/examples/poll/slides.md

@@ -0,0 +1,127 @@
+---
+theme: duet
+meta:
+  title: "Ask the room"
+  author: "Tilman Schieber"
+  organization: "FHNW"
+  date: "2026-09-30"
+---
+
+---
+:::meta
+layout: title
+:::
+# Ask the room.
+## Live questions in a plain slide file.
+
+:::notes
+Start this deck with `mdeck run slides.md --network` so phones in the same network can answer.
+
+The deck shows every kind of question mdeck has: a poll, a scale, a word cloud and open answers. The QR code appears once, on the next slide.
+:::
+
+---
+# Take out your phone.
+
+<qrcode join />
+
+:::notes
+Leave this up until most people have scanned. The code is the same for the whole talk: phones that joined now follow along, and each question appears on them when its slide comes up.
+
+Come back to this slide for latecomers, or leave the join code on the last question too.
+:::
+
+---
+:::meta
+title: "Poll: how do you make slides?"
+:::
+# How do you make slides today?
+
+<poll room="tools" options="PowerPoint|Keynote|Google Slides|LaTeX Beamer|Markdown" qr="false" />
+
+:::notes
+A poll: one button per answer. Give people half a minute and read out the leader once the bars settle.
+
+Anyone can change their answer: only the latest vote from each phone counts.
+
+Before the talk, hover over the results and click Reset to clear test votes.
+:::
+
+---
+:::meta
+title: "Scale: Markdown"
+:::
+# How well do you know Markdown?
+
+<scale room="markdown" min="1" max="5" low="Never used it" high="Every day" qr="false" />
+
+:::notes
+A scale: phones show the numbers from 1 to 5, the slide counts each one and shows the average.
+
+A high average means the rest of the talk can go faster.
+:::
+
+---
+:::meta
+title: "Word cloud: slides"
+:::
+# One word for your last presentation?
+
+<wordcloud room="mood" placeholder="One word" qr="false" />
+
+:::notes
+A word cloud: people may send as many words as they like. The more often a word comes in, the larger it gets, packed around the middle; capitals do not matter.
+
+Pick out the largest word and one surprising small one.
+:::
+
+---
+:::meta
+title: "Open question"
+:::
+# What would you like to ask?
+
+<question room="ask" placeholder="Your question" qr="false" />
+
+:::notes
+Open answers: the newest eight appear as cards, and people can send several.
+
+Answer one or two now, and promise to go through the rest afterwards; the room keeps them until you reset it.
+:::
+
+---
+# Each question is one line.
+
+```markdown
+<qrcode join />
+<poll room="tools" options="PowerPoint|Keynote|Markdown" />
+<scale room="markdown" min="1" max="5" low="Never" high="Daily" />
+<wordcloud room="mood" />
+<question room="ask" placeholder="Your question" />
+```
+
+- **room** — a short name, different for every question in the deck.
+- **qr="false"** — leave out the code when `<qrcode join />` showed it earlier.
+- **question** — optional; without it, phones show the slide heading.
+
+:::notes
+Point at the lines that made the previous slides. That is all the author writes.
+
+The QR code takes the slide's colours, so it fits every theme; phone cameras read light-on-dark codes too.
+:::
+
+---
+# Try it on your own computer.
+
+```sh
+mdeck run slides.md --network
+```
+
+- **Same network** — phones must be able to reach your computer.
+- **Lecture hall** — run `mdeck server` on a web server; the slides stay on your laptop.
+
+:::notes
+For a lecture hall, run `mdeck server` on a web server once and point the deck's `server` setting at it. The phones only talk to that server; the slides never leave this laptop. The "Ask your audience" guide has the details.
+
+Many university networks keep devices apart. If phones cannot open the page, use a phone hotspot or a server on the internet.
+:::

package/examples/python/.mdeck-backups/slides.drawings-2026-10-06T08-36-47Z.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {
+    "the-tools-your-field-uses-are-written-in": [
+      {"id":"63zmhi:muvocmul6","tool":"pen","color":"#f59e0b","size":6,"points":[[531,278,0.5],[502,280,0.5],[481,280,0.5],[482,282,0.5],[493,284,0.5],[532,286,0.5],[859,286,0.5],[925,293,0.5],[977,298,0.5],[1013,302,0.5],[1146,312,0.5],[1204,317,0.5],[1281,322,0.5],[1299,324,0.5],[1451,332,0.5],[1470,334,0.5],[1507,336,0.5],[1525,338,0.5],[1544,339,0.5],[1579,343,0.5],[1597,344,0.5],[1682,355,0.5],[1747,360,0.5]]}
+    ],
+    "variables-and-data-types": [
+      {"id":"63zmhi:muvocong7","tool":"pen","color":"#f59e0b","size":6,"points":[[734,266,0.5],[699,289,0.5],[690,298,0.5],[678,315,0.5],[673,326,0.5],[665,347,0.5],[659,369,0.5],[658,382,0.5],[658,439,0.5],[662,450,0.5],[677,470,0.5],[686,481,0.5],[706,498,0.5],[718,507,0.5],[742,519,0.5],[753,524,0.5],[765,528,0.5],[777,529,0.5],[805,529,0.5],[812,528,0.5],[818,521,0.5],[823,512,0.5],[827,502,0.5],[830,490,0.5],[836,451,0.5],[838,412,0.5],[838,369,0.5],[837,362,0.5],[835,356,0.5],[831,350,0.5],[826,345,0.5],[811,342,0.5],[805,343,0.5],[793,343,0.5],[787,344,0.5],[781,347,0.5],[775,352,0.5],[760,377,0.5],[755,393,0.5],[755,420,0.5],[760,429,0.5],[768,432,0.5],[787,436,0.5],[884,436,0.5],[900,435,0.5],[915,432,0.5],[931,428,0.5],[961,416,0.5],[975,409,0.5],[986,401,0.5],[999,393,0.5],[1020,377,0.5],[1043,355,0.5],[1052,343,0.5],[1055,335,0.5],[1055,332,0.5],[1054,332,0.5],[1051,337,0.5],[1046,348,0.5],[1045,354,0.5],[1045,392,0.5],[1048,398,0.5],[1058,408,0.5],[1071,416,0.5],[1080,417,0.5],[1096,421,0.5],[1149,421,0.5],[1158,419,0.5],[1175,412,0.5],[1199,393,0.5],[1217,377,0.5],[1232,360,0.5],[1247,345,0.5],[1251,342,0.5],[1263,336,0.5],[1275,332,0.5],[1282,331,0.5],[1324,331,0.5],[1347,338,0.5],[1396,363,0.5],[1411,368,0.5],[1424,371,0.5],[1440,373,0.5],[1456,373,0.5]]}
+    ],
+    "variables-store-data": [
+      {"id":"63zmhi:muvocqi48","tool":"pen","color":"#f59e0b","size":6,"points":[[831,368,0.5],[793,362,0.5],[788,366,0.5],[793,375,0.5],[793,437,0.5],[798,461,0.5],[803,471,0.5],[811,483,0.5],[820,491,0.5],[830,499,0.5],[841,507,0.5],[854,513,0.5],[883,519,0.5],[898,521,0.5],[913,522,0.5],[1010,522,0.5],[1026,519,0.5],[1053,510,0.5],[1075,493,0.5],[1083,484,0.5],[1091,472,0.5],[1098,460,0.5],[1104,445,0.5],[1110,416,0.5],[1112,385,0.5],[1111,370,0.5],[1111,344,0.5],[1109,322,0.5],[1106,313,0.5],[1092,300,0.5],[1080,293,0.5],[1059,290,0.5],[1057,291,0.5],[1052,291,0.5],[1051,292,0.5],[1051,331,0.5],[1060,345,0.5],[1076,360,0.5],[1084,366,0.5],[1117,383,0.5],[1129,387,0.5],[1140,390,0.5],[1164,392,0.5],[1186,392,0.5],[1195,391,0.5],[1204,391,0.5],[1211,384,0.5],[1216,375,0.5],[1220,364,0.5],[1225,340,0.5],[1228,293,0.5],[1228,251,0.5],[1228,255,0.5],[1230,258,0.5],[1235,268,0.5],[1240,273,0.5],[1258,291,0.5],[1282,310,0.5],[1299,321,0.5],[1322,330,0.5],[1334,334,0.5],[1360,340,0.5],[1387,344,0.5],[1414,345,0.5],[1499,345,0.5],[1510,344,0.5],[1520,340,0.5],[1547,331,0.5],[1570,325,0.5],[1587,323,0.5],[1641,323,0.5],[1661,328,0.5],[1718,352,0.5],[1742,360,0.5],[1755,363,0.5]]}
+    ],
+    "four-types-cover-most-biology-data": [
+      {"id":"63zmhi:muvocsxn9","tool":"pen","color":"#f59e0b","size":6,"points":[[1110,277,0.5],[1072,262,0.5],[1059,259,0.5],[1050,260,0.5],[1026,256,0.5],[1002,254,0.5],[935,254,0.5],[923,255,0.5],[900,261,0.5],[851,281,0.5],[838,289,0.5],[824,297,0.5],[795,314,0.5],[779,323,0.5],[747,342,0.5],[731,350,0.5],[716,359,0.5],[669,382,0.5],[654,390,0.5],[642,395,0.5],[592,422,0.5],[587,427,0.5],[583,431,0.5],[582,434,0.5],[582,445,0.5],[591,455,0.5],[610,464,0.5],[622,467,0.5],[662,477,0.5],[679,479,0.5],[716,481,0.5],[889,481,0.5],[907,479,0.5],[922,475,0.5],[948,465,0.5],[958,459,0.5],[964,453,0.5],[970,444,0.5],[974,437,0.5],[975,427,0.5],[975,393,0.5],[968,367,0.5],[962,354,0.5],[941,328,0.5],[919,305,0.5],[896,284,0.5],[883,275,0.5],[856,262,0.5],[841,257,0.5],[814,252,0.5],[800,252,0.5],[787,251,0.5],[773,252,0.5],[749,252,0.5],[738,256,0.5],[728,263,0.5],[711,278,0.5],[697,296,0.5],[687,314,0.5],[684,324,0.5],[682,343,0.5],[683,352,0.5],[683,369,0.5],[686,379,0.5],[699,396,0.5],[721,413,0.5],[745,427,0.5],[773,438,0.5],[803,446,0.5],[834,453,0.5],[865,455,0.5],[881,455,0.5],[896,456,0.5],[910,455,0.5],[939,455,0.5],[966,450,0.5],[980,444,0.5],[1003,433,0.5],[1022,418,0.5],[1033,412,0.5],[1040,404,0.5],[1055,390,0.5],[1066,377,0.5],[1073,367,0.5],[1081,356,0.5],[1082,353,0.5],[1085,348,0.5],[1091,344,0.5],[1132,344,0.5],[1145,351,0.5],[1161,360,0.5],[1190,376,0.5],[1212,384,0.5],[1237,392,0.5],[1279,399,0.5],[1310,401,0.5],[1498,401,0.5],[1509,400,0.5],[1559,398,0.5],[1568,396,0.5],[1631,396,0.5],[1649,400,0.5],[1654,403,0.5],[1664,407,0.5],[1684,412,0.5],[1690,413,0.5],[1707,414,0.5],[1725,414,0.5]]}
+    ]
+  }
+}

package/examples/python/.mdeck-backups/slides.drawings-2026-10-06T11-27-30Z.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {}
+}

package/examples/python/slides.drawings.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {}
+}