mdeck 2.3.0

package/docs/reference/claude-skill.md

@@ -0,0 +1,96 @@
+# Work with an AI assistant
+
+The usual way to make an mdeck presentation is to give an AI assistant the
+material you already have (old slides, a PDF, a Word document, a paper, a page
+of notes) and let it turn that into a deck. The content stays yours; the
+assistant shapes it into slides, chooses layouts, writes speaker notes from
+your text, and checks its work with mdeck.
+
+mdeck ships a skill, `write-slides`, for this. It reads the mdeck reference
+docs, asks the installed `mdeck` command which layouts, themes and palettes the
+deck can use (including designs kept in the deck's `extensions/` folder),
+writes the file, and runs `mdeck check` on the result.
+
+The skill is written in the [Agent Skills](https://agentskills.io) format, a
+`SKILL.md` file that Claude Code, OpenAI Codex and other assistants read
+directly. For tools with their own conventions, `mdeck skill` writes the same
+instructions in their format.
+
+## Install it
+
+```sh
+mdeck skill                        # list the supported assistants
+mdeck skill --install claude       # Claude Code, personal (~/.claude/skills/)
+mdeck skill --install codex        # OpenAI Codex, personal (~/.codex/skills/)
+mdeck skill --install cursor       # Cursor rule in this project (.cursor/rules/)
+mdeck skill --install copilot      # GitHub Copilot prompt file (.github/prompts/)
+mdeck skill --install gemini       # Gemini CLI command (.gemini/commands/)
+mdeck skill --install claude codex --project   # into this project instead of your home folder
+mdeck skill --print                # the skill as text, for any other tool
+```
+
+Run the command in the folder of the deck you are working on when installing
+project-level files. Re-run it after updating mdeck to pick up changes.
+
+## Start a deck
+
+Copy your material into the talk's folder, open the assistant there, and say
+what to make from it: for whom, how long, in which language, and how closely
+to keep to the original.
+
+```prompt
+/write-slides Rebuild kinetics-2023.pptx as a 45-minute lecture for
+second-year biology students, in German, FHNW theme. Keep the order
+and the figures, split the crowded slides, and add what is new in
+notes/2026-changes.md.
+```
+
+| Assistant | How to start |
+|---|---|
+| Claude Code, Gemini CLI | `/write-slides` followed by your request |
+| Codex | Ask for slides; the skill is picked up by its description |
+| Cursor | Mention `@write-slides` or ask for an mdeck deck |
+| GitHub Copilot | Run the `write-slides` prompt from the prompt picker |
+| Anything else | Paste the output of `mdeck skill --print` followed by your request |
+
+The assistant writes a `.md` file named after the topic, checks it, and tells
+you what it left out or added. Open the preview and leave it running while you
+work; it reloads every time the file changes:
+
+```sh
+mdeck run <deck>.md
+```
+
+## Change it by asking
+
+Keep talking to the assistant and watch the slides follow:
+
+```prompt
+You dropped the comparison table from page 12 of the PDF. Put it back
+after the methods slide, and turn "Why it matters" into a big statement.
+```
+
+The assistant can also make what would otherwise need CSS or JavaScript: a
+colour palette, a theme, a slide layout, or an interactive component. They are
+kept as small folders in `extensions/` or `components/` beside the slide file,
+so they travel with the talk. For a theme or palette, it asks you to look at
+the result with `mdeck design <deck>.md`, which shows it on a sample deck with
+every kind of slide, light and dark, and lets you fine-tune colours, fonts and
+sizes yourself.
+
+For a word or a number, it is often faster to edit the file yourself; see
+[Read and adjust your slides](writing.html).
+
+## Check what it wrote
+
+`mdeck check` finds missing pictures and settings mistakes. It does not know
+whether the talk is right, or whether the text fits on each slide. Before
+presenting, compare the deck with your material, look at every slide in the
+preview, and try any polls with a phone.
+
+## What the skill knows
+
+It carries a short quick reference of the file format so it can work even
+without the docs, finds the full reference docs in the repository or the
+installed package, and prefers the live answers from `mdeck list layouts --json`
+and `mdeck list` over its own memory.

package/docs/reference/extensions.md

@@ -0,0 +1,250 @@
+# Extensions: layouts, themes and palettes
+
+mdeck can be extended in three ways, and all three follow the same rules.
+
+- A **layout** is an arrangement for a slide: which content areas it has, which
+  settings it accepts, and how it is arranged. The built-in layouts such as
+  `title` and `split` are extensions too.
+- A **theme** is the overall look: fonts, spacing, the slide frame and the
+  default colours. A deck picks one with `theme:`.
+- A **palette** is a family of colours, light and dark, that repaints any
+  theme. A deck picks one with `palette:` and the variant with `appearance:`.
+
+Every extension is a folder with an `extension.toml` file inside. The manifest
+says which kind it is and describes its supporting files and settings. The
+folder name is the identifier used in slide files.
+
+```text
+extensions/
+  comparison/          a layout
+    extension.toml
+    layout.jsx
+    styles.css
+    starter.md
+  my-theme/            a theme
+    extension.toml
+    styles.css
+  my-colors/           a palette
+    extension.toml
+```
+
+mdeck looks in two places, in this order: its own built-in collection under
+`assets/extensions/` and an `extensions/` folder beside the slide file. Inside
+either place, a folder that contains `extension.toml` is an extension; any other
+folder is simply a group and is searched further, so `extensions/colors/ocean/`
+works just as well as `extensions/ocean/`. Identifiers must be unique within
+their kind across both places. A local extension cannot quietly replace a
+built-in one; a duplicate stops the command with a message naming both files.
+
+The same registry backs `mdeck check`, `mdeck list`, `mdeck list layouts`,
+the `mdeck new` wizard, the dev server and builds, so what a check accepts is
+what a build can load.
+
+## Shared settings
+
+```toml
+schema = 1              # manifest format version; always 1 for now
+kind = "palette"        # layout, theme or palette
+id = "ocean"            # must equal the folder name
+title = "Ocean"         # readable name shown in lists and controls
+description = "Deep blue with a warm highlight."   # optional
+```
+
+- `id` uses lowercase letters, digits and hyphens and starts with a letter.
+- Unknown settings are errors, so a typo is reported rather than ignored.
+- File references are relative to the extension folder and may not leave it.
+- Manifests are [TOML 1.0](https://toml.io/en/v1.0.0). CSS custom property
+  names start with dashes, so quote them as keys: `"--accent" = "#ff0000"`.
+
+Problems are reported with the file, the setting and, for syntax errors, the
+line and column:
+
+```text
+extensions/ocean/extension.toml: light.accent: token names look like "--accent"
+extensions/ocean/extension.toml:7:12: incomplete declaration: value expected
+```
+
+## Palette
+
+```toml
+schema = 1
+kind = "palette"
+id = "ocean"
+title = "Ocean"
+description = "Deep blue with a warm highlight."
+# theme = "my-theme"         # only this theme may use it
+
+[light]
+"--bg" = "#f4f8fb"
+"--surface" = "#e6eef4"
+"--ink" = "#0b1d2a"
+"--ink-soft" = "#22394a"
+"--muted" = "#4f6474"
+"--rule" = "#c9d7e2"
+"--accent" = "#0a6aa8"
+"--accent-2" = "#b45309"
+"--on-accent" = "#ffffff"
+
+[dark]
+"--bg" = "#102030"
+"--surface" = "#17293b"
+"--ink" = "#eef4f8"
+"--ink-soft" = "#c8d6e0"
+"--muted" = "#8ea3b3"
+"--rule" = "#24384b"
+"--accent" = "#ffbd69"
+"--accent-2" = "#7cc4ff"
+"--on-accent" = "#102030"
+```
+
+`[light]` and `[dark]` each set all nine colours, the shared vocabulary every
+theme uses; see [palettes](palettes.md) for what each one does. The deck's
+`appearance` picks one for the slides; themes use the other for inverted
+slides, as `--inverse-*`. The dark variant also gets dark code colours and an
+inverted logo. `theme` makes the palette private to one theme.
+
+## Layout
+
+```toml
+schema = 1
+kind = "layout"
+id = "comparison"
+title = "Side-by-side comparison"
+description = "Two options next to each other."
+frame = "standard"          # standard, title, chapter or none
+
+[files]
+layout = "layout.jsx"       # default; may be omitted
+styles = "styles.css"       # optional; picked up automatically when present
+starter = "starter.md"      # optional; picked up automatically when present
+
+[regions.body]
+description = "Heading and introduction"
+
+[regions.left]
+required = true
+
+[regions.right]
+required = true
+
+[properties.emphasis]
+type = "string"
+enum = ["none", "left", "right"]
+default = "none"
+```
+
+`regions` must include `body`. `properties` describe values under a slide's
+`props:` and support `type` (`string`, `number`, `integer`, `boolean`, `array`,
+`object`), `default`, `enum`, `required`, `minimum`, `maximum`, `minItems`,
+`maxItems`, `items`, plus `title` and `description` for editors. Nested
+settings use TOML sub-tables:
+
+```toml
+[properties.ratio]
+type = "array"
+minItems = 2
+maxItems = 2
+default = [1, 1]
+
+[properties.ratio.items]
+type = "number"
+minimum = 0.01
+```
+
+The layout file is Preact JSX that imports from `mdeck/layout`. See
+[layouts](layouts.md) for the renderer contract. Layout code runs as part
+of the deck: it is trusted code, not sandboxed data.
+
+## Theme
+
+```toml
+schema = 1
+kind = "theme"
+id = "my-theme"
+title = "My theme"
+description = "Calm sans-serif slides."
+palette = "lagoon"           # the default palette; colours come only from palettes
+# palettes = ["lagoon"]      # offer only these palettes
+# appearance = "dark"        # start dark
+fonts = [
+  "https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap",
+]
+
+[files]
+styles = "styles.css"        # one stylesheet or a list of them
+
+[tokens]
+"--fs-body" = "34px"
+"--font-body" = "\"Inter\", system-ui, sans-serif"
+
+[params.fontBody]
+token = "--font-body"
+title = "Body font"
+```
+
+- `palette` names the palette the theme uses unless the deck sets one. A theme
+  has no colours of its own; `tokens` may not set the nine palette colours.
+- `palettes` limits the palettes a theme offers, for a corporate design; it
+  must include the default. Without it, every palette not private to another
+  theme is offered.
+- `appearance = "dark"` makes the theme start dark.
+- `tokens` are the theme's type, spacing and font values. mdeck generates the
+  `:root` block from them, so the stylesheet only contains rules.
+- `params` name the settings authors may change under `params:` in the deck.
+  Each points at a token; its default is the token's value, so nothing is
+  written twice.
+- `fonts` are stylesheet URLs. Normal builds load them; single files (`mdeck send`,
+  `--single-file`) and PDFs embed their Latin character sets, so they look the
+  same offline. The fallbacks named in the token values apply when a font
+  cannot be fetched.
+
+Values are applied in this order: the palette's colours (the deck's variant,
+and the other as `--inverse-*`), the theme's tokens, then deck `params`.
+
+## Editing in the browser
+
+`mdeck design my-talk.md` (also *Design themes* in `mdeck edit`) opens a
+design page for themes and palettes: forms with a live preview on a sample
+deck that has every built-in layout, or on the deck itself. `mdeck design
+<folder>` does the same without a deck and writes to `<folder>/extensions/`.
+Built-in extensions cannot be changed; copy one under a new id to change it.
+New themes always start as a copy. Layouts are not edited there. The page
+writes the same files described above.
+
+## Installed extensions and packs
+
+mdeck looks for extensions in three places, in this order: the built-in ones,
+the user's folder (`~/.mdeck/extensions`, or `$MDECK_HOME/extensions`), and the
+`extensions/` folder beside the deck. An id may appear only once, except that a
+deck's own extension replaces a user one with the same id (with a warning).
+`mdeck check` warns when a deck uses a theme or palette from the user's folder,
+because the slide file then works only on that computer.
+
+`mdeck themes install <pack>` copies a pack from the theme repository into the
+deck's folder, or with `--global` into the user's. A pack is a folder with a
+`pack.toml` (`schema`, `id`, `title`, `description`, `version`, `author`,
+`license`, `homepage`, and `mdeck = ">=X.Y.Z"`, the oldest mdeck it works with)
+and one folder per theme or palette, each holding only `extension.toml` and,
+for a theme, `styles.css`. Theme fonts must come from `https://fonts.googleapis.com/`
+or `https://fonts.bunny.net/`, and `styles.css` may contain neither `@import`
+nor `url()` other than `data:` URLs. Each installed folder gets a
+`.mdeck-pack.json` with the pack, its version, its source and a checksum of
+every file; `update` and `remove` refuse to touch files changed since then
+unless given `--force`.
+
+The repository serves `index.json` (`{ schema: 1, packs: [...] }`, each with
+its ids, `url`, `sha256` and `previews`) and one JSON file per pack version
+holding the text of its files. `mdeck themes build <packs> -o <out> [--check]`
+writes both from a folder of packs; `MDECK_THEMES_URL` points mdeck at another
+index.
+
+## Listing what is available
+
+```sh
+mdeck list my-talk.md
+mdeck list my-talk.md --json
+```
+
+The JSON form carries every manifest's title, description, tokens, parameters,
+region requirements and property definitions, so other tools can build
+controls from the same data mdeck uses.

package/docs/reference/layouts.md

@@ -0,0 +1,153 @@
+# User-created slide layouts
+
+Layouts define slide structure; themes supply typography and colors. Every
+built-in layout and every deck-local layout uses the same registry, manifest,
+property resolver, and slide frame. A local layout requires no framework edit.
+
+```text
+my-talk/
+  slides.md
+  extensions/
+    comparison/
+      extension.toml
+      layout.jsx
+      styles.css       optional
+      starter.md       optional
+```
+
+A layout is one kind of [extension](extensions.md); themes and palettes use
+the same folder and manifest rules. The folder name is the `layout:` value.
+Names must be lowercase letters, digits and hyphens, beginning with a letter.
+A local layout cannot use a built-in's name. Manifests are checked when
+loading, building, listing or validating a deck. The dev server reloads when
+extension files are changed, added or removed.
+
+## Manifest
+
+```toml
+schema = 1
+kind = "layout"
+id = "comparison"
+title = "Side-by-side comparison"
+
+[regions.body]
+description = "Shared heading"
+
+[regions.left]
+required = true
+
+[regions.right]
+required = true
+
+[properties.emphasis]
+type = "string"
+enum = ["none", "left", "right"]
+default = "none"
+```
+
+`regions` must include `body`, which contains unassigned slide Markdown.
+Authors fill additional regions using `:::slot left`, etc. A region can declare
+`required: true` and a human-readable `description`. Unknown region names and
+missing required content are validation errors.
+
+`properties` describes values under slide metadata `props:`. Supported types:
+`string`, `number`, `integer`, `boolean`, `array`, `object`. The schema supports
+`required`, `default`, `enum`, numeric `minimum`/`maximum`, array `items`
+(a `[properties.name.items]` sub-table), `minItems`/`maxItems`, and `title`
+and `description` for editors. This is a small schema subset, not full JSON Schema.
+Defaults are copied for each slide. Unknown properties and invalid values are
+errors. Built-ins also accept their legacy top-level properties such as `image:`.
+
+An optional `frame` selects `standard` (default), `title`, `chapter`, or `none`.
+The last omits header/footer chrome; it still retains the slide container,
+footnotes, ID, and navigation behavior.
+
+## Renderer
+
+`layout.jsx` default-exports a Preact component. It renders the slide body:
+
+```jsx
+import { h } from 'preact'
+import { MarkdownRegion } from 'mdeck/layout'
+
+export default function Comparison({ regions, props }) {
+  return <div class="slide-body">
+    <MarkdownRegion region={regions.body} />
+    <div class="comparison-options">
+      <MarkdownRegion region={regions.left} />
+      <MarkdownRegion region={regions.right}
+        class={props.emphasis === 'right' ? 'is-emphasized' : ''} />
+    </div>
+  </div>
+}
+```
+
+The component receives `regions`, resolved typed `props`, slide `meta`, `id`,
+default-body `content`, `deckConfig`, `index`, `total`, and `manifest`.
+Use `preact/hooks` for interactive layouts. `MarkdownRegion` renders Markdown
+and hydrates both built-in and deck-local components. It exposes a `data-region`
+attribute for integrations. Footnotes are numbered across all regions and placed
+in the shared frame.
+
+For a picture from a property, render `<Picture src={props.image} alt={props.alt}
+fit={props.fit} position={props.position} class="…" />` instead of an `<img>`.
+It is an `<img>` for ordinary pictures; an SVG that uses the palette's colours
+(`var(--accent)` …) is drawn inline so it follows the theme. `themedSvg(src)`
+returns that SVG's markup, or nothing, for layouts that place it themselves.
+
+The framework wraps the result in `SlideFrame`; do not add a second `<section>`
+or frame in your renderer. `SlideFrame`, `MarkdownRegion`, and `HtmlContent` are
+also exported from `mdeck/layout` for integrations, and so is `t(key)`, which
+returns a word the audience sees in the deck's language (`t('slide.chapter')`
+is "Chapter", or "Kapitel" with `lang: de`). The API import resolves
+through mdeck's build plugin, including when the deck is outside the framework.
+
+Keep CSS scoped to `.slide--comparison` and use theme variables:
+
+```css
+.slide--comparison .comparison-options {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 40px;
+}
+.slide--comparison .is-emphasized { color: var(--accent); }
+```
+
+JSX imports of assets and dependencies follow the same build rules as deck-local
+components. Layout CSS is included in both bundle and self-contained builds.
+Local paths in Markdown images, media `src`, and `image:`/`props.image` are handled
+by asset packaging. For other custom asset properties, import assets in JSX so
+Vite can track them; arbitrary string properties are not treated as file paths.
+Renderers must consume their declared regions; the framework validates the
+manifest and authored values, but cannot prove what arbitrary JSX renders.
+
+## Starters and discovery
+
+`starter.md` is an editable slide preset. It should contain explicit `:::meta`
+and placeholder region content, without a leading slide separator. `layout.jsx`,
+`styles.css` and `starter.md` are picked up automatically from the layout
+folder; use a `[files]` table in the manifest to point at different names.
+`mdeck new` lists built-in and local starters found beside the requested output deck.
+
+```sh
+mdeck list layouts slides.md
+mdeck list layouts slides.md --json
+mdeck list layouts slides.md --starter comparison
+mdeck list slides.md
+mdeck check slides.md --strict
+```
+
+The JSON listing is the serializable manifest registry, suitable for completion,
+layout galleries, or future editor inspectors. Listing and validation do not
+execute layout JSX. Packages and a visual editor are not implemented here.
+
+Built-in layouts are ordinary layouts under the framework's
+`assets/extensions/layouts/` folder and use the same `mdeck/layout`
+import, so they double as worked examples.
+
+See the runnable [custom layout example](../../examples/custom-layouts/slides.md):
+
+```sh
+mdeck run examples/custom-layouts/slides.md
+mdeck build examples/custom-layouts/slides.md
+```

package/docs/reference/palettes.md

@@ -0,0 +1,106 @@
+# Palettes
+
+A palette gives a deck its colours. It is the only place colours come from: themes set type, spacing and layout, and leave colour to the palette, so any palette fits any theme.
+
+Every palette is a family with two variants, **light** and **dark**. A deck chooses the family with `palette:` and the variant with `appearance:`. Themes use the *other* variant for inverted slides, such as neue's statement slides, so those stay readable and in tune.
+
+## Using a palette
+
+```yaml
+---
+theme: neue
+palette: terra        # optional; without it the theme's default palette
+appearance: dark      # optional: light or dark; without it the theme's default
+---
+```
+
+The presenter view and the reader view switch palette and light or dark without changing the file. Choose dark for a dark lecture hall, light for a bright seminar room.
+
+## Built-in palettes
+
+| Palette | Light | Dark |
+|---|---|---|
+| `lagoon` | teal on warm stone, orange second accent | deep teal-black, bright teal |
+| `swiss` | white, black and signal red | black, white and red |
+| `cobalt` | ultramarine on white, vivid orange second accent | deep navy with a luminous blue |
+| `nordic` | ice grey, deep navy and a cool steel blue | polar night with ice blue |
+| `graphite` | black and white with a steel-blue accent | charcoal with light steel blue |
+| `terra` | cream, deep navy and brick red | deep navy, cream and coral |
+| `forest` | deep green with moss and ochre | forest night with light green |
+| `ember` | sand and espresso with orange | dark brown with glowing orange |
+| `neon` | white with violet and magenta | black with neon violet and pink |
+| `phosphor` | a printout: near-black on paper, green and ochre | a terminal screen: phosphor green on black, amber |
+| `pastel` | Catppuccin Latte: soft grey-blue paper, mauve and peach | Catppuccin Mocha: dusk blue with pastel mauve and peach |
+
+`mdeck list palettes` lists them, with any of your own.
+
+Each theme names a default: neue uses `swiss`, editorial `terra`, duet `cobalt`, aurora `neon`, terminal `phosphor` (dark), academic `nordic`, sketch `pastel`. The FHNW theme uses its own palette `brand` (FHNW yellow, black and white) and offers no other.
+
+## Colours
+
+Every variant sets all nine:
+
+| Colour | Role |
+|---|---|
+| `--bg` | Slide background |
+| `--surface` | Raised surfaces: code blocks, image panes, cards |
+| `--ink` | Headings and primary text |
+| `--ink-soft` | Body text |
+| `--muted` | Small labels: headers, footers, captions |
+| `--rule` | Lines and dividers |
+| `--accent` | The highlight: emphasis, markers, chapter slides |
+| `--accent-2` | A second highlight for themes that pair two |
+| `--on-accent` | Text set on the accent, such as a chapter slide's title |
+
+Themes may mix them (for example a light tint of the accent), and read the other variant as `--inverse-bg`, `--inverse-ink`, `--inverse-accent` and so on.
+
+## Making a palette
+
+A palette is an [extension](extensions.md): a folder named after it with an `extension.toml`, in `extensions/` beside a deck.
+
+```toml
+schema = 1
+kind = "palette"
+id = "harbour"
+title = "Harbour"
+description = "Sea blue and rust on chalk white."
+
+[light]
+"--bg" = "#f7f9fa"
+"--surface" = "#e9eef1"
+"--ink" = "#0b1d2a"
+"--ink-soft" = "#22394a"
+"--muted" = "#4f6474"
+"--rule" = "#c9d7e2"
+"--accent" = "#0a6aa8"
+"--accent-2" = "#b45309"
+"--on-accent" = "#ffffff"
+
+[dark]
+"--bg" = "#0d1a24"
+"--surface" = "#152635"
+"--ink" = "#eef4f8"
+"--ink-soft" = "#c8d6e0"
+"--muted" = "#8ea3b3"
+"--rule" = "#24384b"
+"--accent" = "#5fb3f0"
+"--accent-2" = "#f59e5b"
+"--on-accent" = "#0d1a24"
+```
+
+Colour names start with dashes, so quote them as TOML keys. A dark variant also gets dark code colours and an inverted logo; set `--logo-filter` or the `--token-*` code colours in `[dark]` to change that.
+
+`theme = "my-theme"` makes a palette private: only that theme offers it, as FHNW does with `brand`.
+
+## Readability
+
+`mdeck check` measures the contrast of your palette's colours and warns when they are too close to read from the back of a room:
+
+| Pair | At least |
+|---|---|
+| text (`--ink`) on the background | 7 : 1 |
+| body text and muted text on the background | 4.5 : 1 |
+| both accents on the background | 3 : 1 (large type) |
+| text on the accent | 3 : 1 |
+
+The built-in palettes meet these in both variants. A private palette may use its accent only as a surface (FHNW's yellow), so its accents are not checked as text.