mdeck 2.3.0

package/examples/showcase/slides.md

@@ -0,0 +1,427 @@
+---
+theme: aurora
+meta:
+  title: "A tour of mdeck"
+  author: "Tilman Schieber"
+  organization: "FHNW"
+  date: "2026-10-06"
+---
+
+---
+:::meta
+layout: title
+image: ./img/mdeck.svg
+fit: contain
+alt: "A Markdown file turning into a stack of slides"
+id: a-talk-in-a-text-file
+:::
+# A talk in a text file.
+## A tour of mdeck: each slide shows *what is written* and what it becomes.
+
+:::notes
+This deck teaches mdeck by example. Most slides show the Markdown beside what it becomes. Open `slides.md` next to it: every slide here is written exactly as shown.
+
+Go through it with the arrow keys or the space bar. These notes are only for you; open the presenter view from the launch page to see them beside the slide.
+:::
+
+---
+:::meta
+layout: chapter
+number: 1
+part: Writing
+description: Plain Markdown, the format AI assistants already write. You can read and change every word.
+:::
+# Write it.
+
+:::notes
+In practice an AI assistant usually writes this file from your own material: old slides, a document, your notes. The `write-slides` skill teaches it mdeck. The next slides show what it writes, so you can read and adjust it.
+:::
+
+---
+:::meta
+layout: split
+:::
+# Words become slides
+:::slot left
+```markdown
+# Our next adventure
+
+A paragraph of ordinary text.
+
+---
+
+# The next idea
+```
+:::
+:::slot right
+## Our next adventure
+
+A paragraph of ordinary text.
+
+Three dashes on a line of their own start the next slide.
+:::
+
+:::notes
+`#` is the slide's heading. A blank line separates paragraphs.
+
+Try it: change a heading in `slides.md` and save. The slide updates while it is open.
+:::
+
+---
+:::meta
+layout: split
+:::
+# Lists and emphasis
+:::slot left
+```markdown
+- Bring a notebook.
+- Ask **one good question**.
+- Share what *you* learn.
+
+1. Listen
+2. Summarize
+```
+:::
+:::slot right
+- Bring a notebook.
+- Ask **one good question**.
+- Share what *you* learn.
+
+1. Listen
+2. Summarize
+:::
+
+:::notes
+`**bold**` and `*emphasis*`; the theme decides how emphasis looks. In this theme it takes the accent colour.
+:::
+
+---
+# Reveal points one at a time
+
+:::columns
+```markdown
+:::steps
+- First, a question.
+- Then, a pause.
+- Then, the answer.
+:::
+```
++++
+:::steps
+- First, a question.
+- Then, a pause.
+- Then, the answer.
+:::
+:::
+
+:::notes
+Press the next key: each press reveals one point, then moves on. Printed slides and the PDF show all the points.
+
+This slide has no layout: `:::columns` puts the source and the result side by side, and `+++` starts the second column.
+:::
+
+---
+:::meta
+layout: chapter
+number: 2
+part: Layouts and content
+description: Layouts, pictures, code, tables and callouts. Pick a layout per slide; the theme does the rest.
+:::
+# Lay it out.
+
+---
+:::meta
+layout: split
+props:
+  ratio: [3, 2]
+:::
+# Choose a layout
+:::slot left
+```markdown
+:::meta
+layout: focus
+attribution: "A teacher"
+:::
+# Good questions make
+# better conversations.
+```
+:::
+:::slot right
+A `:::meta` block at the top of a slide holds its settings.
+
+`layout: focus` makes one large statement. The next slide is exactly this.
+:::
+
+:::notes
+Without a layout, a slide is an ordinary heading with content. This slide is `layout: split`, with the two sides written as `:::slot left` and `:::slot right`; `ratio: [3, 2]` gives the code more room.
+
+The built-in layouts are `title`, `chapter`, `focus`, `split`, `image-text` and `full-bleed-image`.
+:::
+
+---
+:::meta
+layout: focus
+attribution: "A teacher"
+:::
+# Good questions make better conversations.
+
+---
+:::meta
+layout: image-text
+image: ./img/image.jpg
+alt: "Contour lines like those on a map"
+:::
+# A picture beside your words
+
+```markdown
+:::meta
+layout: image-text
+image: ./img/image.jpg
+alt: "Contour lines"
+:::
+```
+
+`alt` describes the picture for people who cannot see it.
+
+:::notes
+Keep pictures in a folder beside the slides, here `img/`. The next slide uses the same picture with `layout: full-bleed-image`.
+:::
+
+---
+:::meta
+layout: full-bleed-image
+image: ./img/image.jpg
+alt: "Contour lines like those on a map"
+overlay: true
+:::
+# Or let the picture fill the slide.
+
+:::notes
+This slide is written as:
+
+```markdown
+:::meta
+layout: full-bleed-image
+image: ./img/image.jpg
+overlay: true
+:::
+# Or let the picture fill the slide.
+```
+
+`overlay: true` darkens the picture so the heading stays readable.
+:::
+
+---
+:::meta
+layout: split
+:::
+# Code you can run
+:::slot left
+````markdown
+```python live editable
+squares = [x**2 for x in range(1, 6)]
+print(squares)
+```
+````
+:::
+:::slot right
+```python live editable
+squares = [x**2 for x in range(1, 6)]
+print(squares)
+```
+:::
+
+:::notes
+Press Run. `live` adds the button, `editable` lets you change the code while presenting, `copy` adds a copy button. JavaScript works the same way.
+
+Live Python downloads its runtime the first time, so it needs an internet connection.
+:::
+
+---
+:::meta
+layout: split
+:::
+# Tables and formulas
+:::slot left
+```markdown
+| Layer | Who owns it |
+|---|---|
+| Words | You |
+| Look | The theme |
+
+$$
+A = \pi r^2
+$$
+```
+:::
+:::slot right
+| Layer | Who owns it |
+|---|---|
+| Words | You |
+| Look | The theme |
+
+$$
+A = \pi r^2
+$$
+:::
+
+:::notes
+Formulas use LaTeX. Single dollar signs put a formula inside a sentence; two dollar signs above and below put it on its own line.
+:::
+
+---
+:::meta
+layout: split
+:::
+# Tips and warnings
+:::slot left
+```markdown
+:::tip
+One tip per slide is plenty.
+:::
+
+:::warning
+Check the room's projector.
+:::
+```
+:::
+:::slot right
+:::tip
+One tip per slide is plenty.
+:::
+
+:::warning
+Check the room's projector.
+:::
+:::
+
+:::notes
+The other callouts are `note`, `important` and `caution`. Add your own label after the type, for example `:::tip Before the talk`.
+:::
+
+---
+:::meta
+layout: chapter
+number: 3
+part: Presenting
+description: Notes for you, drawing on the slides, and questions for the room.
+id: give-the-talk
+:::
+# Give the talk.
+
+---
+:::meta
+layout: split
+:::
+# Notes only you can see
+:::slot left
+```markdown
+:::notes
+Pause here. Ask who has
+tried this before.
+:::
+```
+:::
+:::slot right
+Notes go below the slide's content. They appear in the **presenter view**, never on the projector.
+
+Open it from the launch page, and move the **audience window** onto the projector. The two follow each other.
+:::
+
+:::notes
+Pause here. Ask who has tried this before.
+
+This is what the presenter view shows for this slide. Its header also shows what is connected: other presenter views, audience windows and phones.
+:::
+
+---
+:::meta
+id: draw-on-any-slide
+:::
+# Draw on any slide
+
+Press **D** now, or the pen button. Draw with a pen, a highlighter, or a marker that fades after a moment. **Escape** stops.
+
+Drawings are kept in `slides.drawings.json` beside the slides, and appear in the PDF.
+
+:::notes
+The underline and the circle on this slide were drawn with the pen and saved; they show in every view and in the PDF.
+
+On an iPad, pair it from the launch page: you draw and steer there while the laptop drives the projector.
+:::
+
+---
+# Which part will you try first?
+
+<poll room="tour" options="Writing|Layouts|Drawing|Polls" />
+
+:::notes
+One line makes a poll; the heading is the question:
+
+`<poll room="tour" options="Writing|Layouts|Drawing|Polls" />`
+
+Phones join with the QR code. They can reach this computer when you start `mdeck run slides.md --network`. The poll example shows scales, word clouds and open questions.
+:::
+
+---
+:::meta
+layout: chapter
+number: 4
+part: Sharing
+description: One file to send, a PDF, or a folder for a website.
+:::
+# Share it.
+
+---
+:::meta
+layout: split
+:::
+# Change the whole look
+:::slot left
+```markdown
+---
+theme: editorial
+palette: terra
+---
+```
+:::
+:::slot right
+Two lines at the top of the file choose the theme and colours for every slide at once.
+
+To try them without changing the file, open the **reader view** and choose **Look**.
+:::
+
+:::notes
+mdeck has six themes and ten palettes, each light or dark. `mdeck list` shows them all, including any kept in an `extensions` folder beside the deck.
+:::
+
+---
+:::meta
+layout: split
+:::
+# Send it, print it, host it
+:::slot left
+```sh
+mdeck send slides.md
+mdeck pdf slides.md
+mdeck build slides.md
+```
+:::
+:::slot right
+`send` makes one HTML file without your notes, with a PDF inside. People open it in a browser.
+
+`pdf` makes one page per slide. `build` makes a folder for a web server.
+:::
+
+---
+:::meta
+layout: title
+:::
+# Now make your own.
+## Hand your slides, documents or notes to an *AI assistant*.
+
+:::notes
+`mdeck skill --install claude` (or codex, cursor, copilot, gemini) installs the `write-slides` skill, which teaches the assistant mdeck. Then point it at your material: “Rebuild lecture-03.pptx as a 20-minute talk.”
+
+Without an assistant, `mdeck new` asks a few questions and starts a deck.
+:::

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "mdeck",
+  "version": "2.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",
+  "author": "Tilman Schieber",
+  "homepage": "https://gh.tschieber.de/mdeck/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tilman-schieber/mdeck.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tilman-schieber/mdeck/issues"
+  },
+  "keywords": [
+    "markdown",
+    "slides",
+    "presentation",
+    "deck",
+    "pdf",
+    "teaching"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "mdeck": "./bin/mdeck.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "docs/README.md",
+    "docs/reference",
+    "docs/site",
+    "!docs/site/dist",
+    "examples",
+    "skills",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:browser": "node tools/browser-check.mjs",
+    "test:server": "node tools/server-check.mjs",
+    "test:docs": "node tools/docs-check.mjs",
+    "test:themes": "node tools/theme-check.mjs",
+    "docs": "node bin/mdeck.js docs",
+    "docs:build": "node docs/site/build.js",
+    "start": "node bin/mdeck.js run",
+    "edit": "node bin/mdeck.js edit",
+    "build": "node bin/mdeck.js build",
+    "preview": "node bin/mdeck.js preview",
+    "playground": "vite --config playground/vite.config.js",
+    "playground:build": "vite build --config playground/vite.config.js",
+    "readme-images": "node tools/readme-images.mjs",
+    "theme-images": "node tools/theme-images.mjs"
+  },
+  "dependencies": {
+    "@preact/preset-vite": "^2.10.6",
+    "d3-cloud": "^1.2.9",
+    "js-yaml": "^4.3.2",
+    "katex": "^0.18.9",
+    "marked": "^18.0.14",
+    "marked-katex-extension": "^5.1.13",
+    "perfect-freehand": "^1.2.3",
+    "preact": "^10.29.8",
+    "prismjs": "^1.30.0",
+    "qrcode": "^1.5.4",
+    "smol-toml": "^1.9.0",
+    "vite": "^8.3.1",
+    "vite-plugin-singlefile": "^2.3.3",
+    "ws": "^8.22.0"
+  }
+}

package/skills/write-slides/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: write-slides
+description: Write a complete mdeck slide deck. Use when the user asks to create slides, a presentation, or a talk using the mdeck framework, including turning existing PowerPoint, PDF, Word documents or notes into a deck, and when they want a new look for mdeck slides (a theme or colour palette, for example in their institute's colours).
+license: MIT
+compatibility: Best with the mdeck command installed (npm install -g mdeck); works without it using the quick reference.
+allowed-tools: Read Write Bash(mdeck:*) Bash(npm root:*) Bash(ls:*)
+metadata:
+  argument-hint: "[source files, audience, length, language]"
+  homepage: https://gh.tschieber.de/mdeck/
+---
+
+You are writing a presentation for mdeck, a slide framework that turns one Markdown file into slides with swappable themes and palettes.
+
+## 1. Find the reference material
+
+The mdeck docs are the source of truth for syntax, layouts and looks. Look for them in this order and read `authoring.md`, `themes.md` and `palettes.md` from the first place that exists:
+
+1. `docs/reference/` in the current folder (you are inside the mdeck repository).
+2. `$(npm root -g)/mdeck/docs/reference/` (mdeck is installed globally).
+
+Read `examples/showcase/slides.md` from the same place as a complete working deck.
+
+Then ask the installed mdeck what this deck can use, because a deck may ship its own layouts, themes and palettes in an `extensions/` folder:
+
+```sh
+mdeck list layouts <deck>.md --json  # every layout with its regions, settings and starter text
+mdeck list <deck>.md                 # layouts, themes and palettes, built-in and local
+```
+
+If `mdeck` is not installed, rely on the quick reference below.
+
+## 2. Quick reference
+
+```markdown
+---
+theme: neue            # theme id from `mdeck list themes`
+palette: terra          # optional: lagoon, swiss, cobalt, nordic, graphite, terra, forest, ember, neon, phosphor, pastel
+appearance: light       # optional: light or dark
+meta:
+  title: "Talk title"
+  author: "Name"
+  organization: "FHNW"
+  date: "2026-09-16"
+---
+
+---
+:::meta
+layout: title
+props:
+  image: ./img/cover.jpg
+:::
+# Headline
+## Subtitle
+
+---
+:::meta
+layout: chapter
+number: 1
+part: Part One
+:::
+# Chapter title
+
+---
+# A content slide
+
+- One point
+- Another point
+
+:::notes
+What to say, what to skip, where to pause.
+:::
+
+---
+:::meta
+layout: split
+props:
+  ratio: [1, 2]
+:::
+# Shared heading
+
+:::slot left
+Left column
+:::
+
+:::slot right
+Right column
+:::
+```
+
+- Slides are separated by `---` on its own line. Settings go in a `:::meta` block at the top of a slide.
+- Built-in layouts: `title`, `chapter`, `focus` (one big statement), `image-text`, `split`, `full-bleed-image`, and plain content slides without a `layout:`.
+- Named areas use `:::slot name … :::`; the layout's regions and settings come from `mdeck list layouts --json`.
+- `:::notes … :::` holds speaker notes. `:::steps … :::` reveals list items one at a time. `:::note`, `:::tip`, `:::important`, `:::warning` and `:::caution` are callouts (`mdeck check` warns about other names); for lectures, `:::definition`, `:::theorem`, `:::lemma`, `:::proof`, `:::example` and `:::remark`, numbered in the title (`::: theorem Theorem 2.4 (Lagrange)`). `:::columns … +++ … :::` makes columns inside a slide.
+- Code fences get syntax highlighting; `$…$` and `$$…$$` render math.
+- `<poll room="lunch" options="Mensa|Thai|Pizza" />` lets the audience vote on their phones through a QR code on the slide; each poll needs its own `room`. `<scale room="pace" min="1" max="5" low="Too slow" high="Too fast" />`, `<wordcloud room="mood" />` and `<question room="ask" />` ask for a rating, short words or open answers the same way. With several of them, put `<qrcode join />` (the deck's join code) on an early slide to show the QR code once, and add `qr="false"` to the questions. It works when the deck is presented with `mdeck run <deck>.md --network` or with a server set as `server:` in the deck settings.
+
+## 3. Write the deck
+
+The request is the message that invoked this skill: usually source material to turn into a deck, plus audience, length and language. If any of those are missing and matter, ask once, then write a complete deck.
+
+**Source material**
+- Most requests point at existing material: a `.pptx` or `.key` deck, a PDF (slides, a paper, a report), a `.docx`, Markdown or plain-text notes, spreadsheets. Read all of it before writing. If the request names no files, look in the deck's folder and ask whether to use what is there.
+- Reuse the material's pictures: copy the ones you use into `./img/` with descriptive names. If you cannot open a file, say so.
+- The material is the content. Keep its argument, order, facts, numbers, examples, terminology and citations; do not add claims, data or examples it does not contain. Your job is the deck: one idea per slide, statement headings, fitting layouts, detail moved from crowded slides into the notes, and notes written from the material's own text.
+- Follow the requested degree of faithfulness. "Keep my wording" means light edits only; "tighten" or a time limit means cutting, and the cuts go into the notes or into your summary, not silently away.
+- When rebuilding an old deck, keep its sequence unless asked otherwise, split slides that carry several ideas, and turn text-heavy slides into a few points with the rest in notes.
+- Without any material, write the content yourself from the brief, and say clearly that it needs checking.
+
+**Structure**
+- Start with the deck settings: pick a `theme` and, if it suits the subject, a `palette` from the lists you gathered; fill in `meta.title`, `meta.author`, `meta.organization`, `meta.date`. For a talk that is not in English, set `lang` (for example `lang: de`).
+- The first slide is `layout: title` with an `h1` headline and an `h2` subtitle.
+- Use `layout: chapter` slides to divide major sections. End with a closing focus or title slide.
+
+**Content**
+- One idea per slide; if a third bullet is tempting, make it a new slide.
+- Headings are statements, not labels ("Tokens decouple design from content", not "Design tokens").
+- Use `layout: focus` for principles, quotes and conclusions; `layout: split` to pair code or an image with an explanation; `layout: full-bleed-image` only when a strong photograph carries the point.
+- Add speaker notes to every content slide: context, transitions, what to emphasise.
+- When the brief asks for audience interaction, add one or two polls at natural pauses, not more, and say in the notes how to present them.
+
+**Formatting**
+- `*italic*` renders in the accent colour; use it for key terms, not decoration.
+- Keep lists to three to five items; prefer a short bold label plus one sentence over long bullets.
+- Reference pictures under `./img/` and say which files the user still needs to add.
+
+## 4. Check and hand over
+
+Save the deck as a `.md` file named after the topic (for example `enzyme-kinetics.md`), then run:
+
+```sh
+mdeck check <deck>.md
+```
+
+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).
+
+## 5. A new look: themes and palettes
+
+When the user wants a look the built-in themes and palettes do not give (their institute's colours, a font, the style of a poster or picture), first run `mdeck themes search` (with a word or two): someone may have shared it, and `mdeck themes install <pack> <deck>.md` puts it beside the deck. Otherwise make it as an extension in `extensions/` beside the deck, never as styling on single slides. Read `extensions.md` from the reference folder first; it lists every setting.
+
+- **Colours only: a palette.** `extensions/<id>/extension.toml` with `kind = "palette"`, and every colour role (`--bg`, `--surface`, `--ink`, `--ink-soft`, `--muted`, `--rule`, `--accent`, `--accent-2`, `--on-accent`) in both `[light]` and `[dark]`. Text colours must stay readable on `--bg` and `--surface` in both variants, because themes use the other variant for inverted slides.
+- **Fonts, sizes, spacing or arrangement: a theme.** Copy the folder of the closest built-in theme (`assets/extensions/themes/<id>/` in the mdeck repository or in `$(npm root -g)/mdeck/`) to `extensions/<new-id>/`, change `id` and `title`, then its tokens and `styles.css`. A theme takes no colours of its own: it names its default `palette`, and the colours come from palettes.
+- **Use it:** set `theme:` and `palette:` in the deck settings. `mdeck list <deck>.md` must show it as local, and `mdeck check <deck>.md` reports any mistake in its `extension.toml`.
+- **Hand over:** tell the user to run `mdeck design <deck>.md` (or `mdeck design <folder>` when there is no deck yet). It shows the look on a sample deck with every kind of slide, light and dark, and lets them fine-tune colours, fonts and sizes there.
+

package/src/build/check.js

@@ -0,0 +1,49 @@
+// Deck validation shared by `mdeck check` and the launch page: source
+// diagnostics plus local files the deck refers to but that are missing.
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { drawingsDiagnostic } from './drawings.js'
+import { parseSlides } from '../core/parseSlides.js'
+import { validateDeck } from '../core/validateDeck.js'
+import { manifestsOf } from '../extensions/discover.js'
+import { paletteProblems } from '../extensions/contrast.js'
+import { collectLocalAssetRefs } from './slidesPlugin.js'
+import { componentFolders, isFolder } from './components.js'
+import { inkFileFor, validateInk, normalizeInk, orphanIds } from '../core/ink.js'
+
+export function checkDeck(slidesPath, registry, source = readFileSync(slidesPath, 'utf8')) {
+  const deck = parseSlides(source)
+  const diagnostics = validateDeck(deck, { layouts: manifestsOf(registry, 'layout'), themes: manifestsOf(registry, 'theme'), palettes: manifestsOf(registry, 'palette') })
+  for (const ref of collectLocalAssetRefs(source)) {
+    if (!existsSync(resolve(dirname(resolve(slidesPath)), ref))) diagnostics.push({ severity: 'error', code: 'missing-asset', message: `Missing local asset: ${ref}`, line: 1, column: 1 })
+  }
+  for (const folder of componentFolders(slidesPath, source).filter(folder => folder.source === 'shared')) {
+    if (!isFolder(folder.dir)) diagnostics.push({ severity: 'error', code: 'missing-components', message: `Components folder not found: ${folder.path} (${folder.dir})`, line: 1, column: 1 })
+  }
+  // The deck's own palettes: colours too close to read are worth knowing
+  // before the talk (the built-in ones are held to this by the tests).
+  for (const record of Object.values(registry.palettes)) {
+    if (record.source !== 'local') continue
+    for (const problem of paletteProblems(record.manifest)) diagnostics.push({ severity: 'warning', code: 'palette-contrast', message: `Palette "${record.id}", ${problem}`, line: 1, column: 1 })
+  }
+  // A theme or palette installed for this user only: the slide file needs it
+  // beside it to work on another computer.
+  const config = deck.deckConfig ?? {}
+  for (const [kind, id] of [['theme', config.theme], ['palette', config.palette]]) {
+    const record = id && registry[`${kind}s`][id]
+    if (record?.source === 'user') diagnostics.push({ severity: 'warning', code: 'user-extension', message: `The ${kind} "${id}" is installed only on this computer (${dirname(record.dir)}); copy it into the deck's extensions folder, for example with mdeck themes install, so the slide file works elsewhere`, line: 1, column: 1 })
+  }
+  // The deck's drawings file: readable, and only for slides that still exist.
+  const inkPath = inkFileFor(resolve(slidesPath))
+  const renamed = drawingsDiagnostic(slidesPath)
+  if (renamed) diagnostics.push(renamed)
+  if (existsSync(inkPath)) {
+    let raw = null
+    try { raw = JSON.parse(readFileSync(inkPath, 'utf8')) } catch (error) { diagnostics.push({ severity: 'error', code: 'invalid-ink', message: `The drawings file is not valid JSON: ${error.message}`, line: 1, column: 1 }) }
+    if (raw) {
+      for (const problem of validateInk(raw)) diagnostics.push({ severity: 'warning', code: 'invalid-ink', message: `Drawings file: ${problem.message}`, line: 1, column: 1 })
+      for (const id of orphanIds(normalizeInk(raw), deck.slides)) diagnostics.push({ severity: 'warning', code: 'ink-orphan', message: `The drawings file has drawings for slide "${id}", which is not in the deck`, line: 1, column: 1 })
+    }
+  }
+  return { deck, diagnostics }
+}