mdeck 2.3.0

package/docs/site/content/media.md

@@ -0,0 +1,107 @@
+# Add pictures and video
+
+Keep your slide file and its pictures together in one folder. That makes the presentation easier to move and share later.
+
+Your assistant can place pictures for you once they are in the folder. Tell it which file belongs where and what it shows:
+
+```prompt
+Put img/garden.jpg on the opening slide, full size, and the three
+photos in img/beds/ side by side on the slide about planting.
+```
+
+When it suggests pictures you do not have yet, it names the files it expects; `mdeck check` lists the ones still missing.
+
+## Keep the files together
+
+For example, your folder could look like this:
+
+```text
+my-talk/
+  my-talk.md
+  img/
+    garden.jpg
+  video/
+    tour.mp4
+```
+
+`img` and `video` are ordinary folders you create. Their names are suggestions, not special mdeck requirements.
+
+## Put a picture on a slide
+
+Write a line like this where you want the picture:
+
+```markdown
+![A community garden in spring](./img/garden.jpg)
+```
+
+The words in square brackets describe the picture. The part in parentheses is its location, starting from the folder containing your slide file. `./` means “start in this folder.”
+
+Use forward slashes in image paths, including on Windows. Simple filenames without spaces are easiest to work with.
+
+For a picture beside text or a picture that fills the slide, use one of the [picture layouts](layouts.html#a-picture-beside-your-words).
+
+## Show the whole picture
+
+Picture layouts usually fill their available space, which can crop the edges. To keep the whole picture visible, use `fit: contain`:
+
+```markdown
+:::meta
+layout: image-text
+props:
+  image: ./img/garden.jpg
+  alt: "A community garden in spring"
+  fit: contain
+:::
+# The whole garden
+```
+
+For a cropped picture, use `fit: cover`. You can add `position: "left center"` or `position: "70% 50%"` to choose which part stays in view.
+
+## Pictures that follow the theme
+
+An SVG drawing can take its colours from the theme, so it matches every theme, palette, and light or dark. Colour it with the palette's names instead of fixed colours, for example `fill: var(--accent, #1f3fd1)`; the colour after the comma is used wherever the picture is shown on its own. The names are `--bg`, `--surface`, `--ink`, `--ink-soft`, `--muted`, `--rule`, `--accent`, `--accent-2` and `--on-accent`.
+
+It works wherever a picture goes: in the slide text (`![…](./img/drawing.svg)`) or as the `image` of a layout. In a layout, add `fit: contain` so the whole drawing shows. The tour example's title picture, `examples/showcase/img/mdeck.svg`, works this way. An AI assistant can draw one for you:
+
+```prompt
+Draw an SVG title picture for this talk that uses the palette's
+colours, with a transparent background, and put it on the title slide.
+```
+
+## Add a video file
+
+Paste this line into a normal slide, or into one side of a split slide:
+
+```html
+<videoplayer src="./video/tour.mp4" />
+```
+
+This is a special instruction to mdeck. You only need to change the filename. The player shows controls so you can choose when to play the video.
+
+To start a video when its slide appears, add `play="auto"`:
+
+```html
+<videoplayer src="./video/tour.mp4" play="auto" />
+```
+
+Automatic playback is muted. Leaving the slide stops the local video; automatic videos also return to the beginning.
+
+## Show an online video
+
+Use `url` instead of `src` for a YouTube, Vimeo, or SwitchTube address:
+
+```html
+<videoplayer url="https://www.youtube.com/watch?v=YOUR_VIDEO_ID" />
+```
+
+Replace the example address with your video's address. Online videos need an internet connection and permission from the video service to appear in another page. Test them before your talk.
+
+## If a picture does not appear
+
+Check the spelling of the filename and folder, including capital letters. Then run:
+
+```sh
+mdeck check my-talk.md
+```
+
+mdeck reports local files it cannot find. For sharing, use a [built presentation](sharing.html), so the necessary files travel with it.

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

@@ -0,0 +1,130 @@
+# Tables, tips, and more
+
+Besides headings and lists, slides can hold tables, callouts, columns, citations, QR codes, formulas and code. Use these when they make an idea easier to understand. Your assistant knows all of them; ask for the content rather than the format:
+
+```prompt
+Compare the three sampling methods in a small table, add a warning
+about contamination, and show the rate equation as a formula.
+```
+
+The examples below show what each looks like in the file.
+
+## Make a table
+
+A table compares things side by side. Vertical lines separate the columns:
+
+```markdown
+| Activity | Bring |
+|---|---|
+| Planting | Gloves |
+| Planning | A notebook |
+| Lunch | Something to share |
+```
+
+Keep tables small enough to read from the back of the room.
+
+## Add a tip or reminder
+
+A callout is a short note with a visible label. Choose `note`, `tip`, `important`, `warning`, or `caution`:
+
+```markdown
+:::tip
+Bring a spare copy of your presentation.
+:::
+```
+
+Add your own label after the type if you prefer:
+
+```markdown
+:::note Before we begin
+Please put your phone on silent.
+:::
+```
+
+With `lang: de` in the settings for the whole presentation, tips and reminders get German labels, as do the buttons people see when you share the slides. You can also customize individual labels:
+
+```yaml
+lang: de
+callouts:
+  tip: "Gut zu wissen"
+```
+
+## Put ordinary content in columns
+
+For two or more equal-width columns within a slide, use a columns block. The `+++` line starts the next column:
+
+```markdown
+# What to bring
+
+:::columns
+## For the garden
+- Gloves
+- Water
++++
+## For the meeting
+- Notebook
+- Questions
+:::
+```
+
+You can put a tip inside a column. Give each opening block its own closing `:::` line. For unequal widths, use the [split layout](layouts.html#two-areas-side-by-side).
+
+## Cite a source
+
+A footnote puts a short reference near the bottom of the slide:
+
+```markdown
+This finding comes from our neighborhood survey.[^survey]
+
+[^survey]: Garden team survey, May 2026.
+```
+
+The name inside the brackets connects the sentence to its source. Give each source a different name.
+
+## Add a QR code
+
+A QR code lets people open a link on their phones. Replace the address below with your own:
+
+```html
+<qrcode url="https://example.com" size="240" />
+```
+
+`size` sets its width in slide pixels. The code takes the slide's text colour on the slide's background, so it fits every theme. If a scanner struggles, give it a white background with `--qr-bg: #fff` and `--qr-ink: #000` in a theme or a `style` around it. Keep enough space around it, and test it on the screen you will use.
+
+To ask the audience a question instead, a poll shows its own QR code and the answers as they come in, and `<qrcode join />` shows the join code for all your questions at once. See [Ask your audience](audience.html).
+
+## Show a formula
+
+Formulas use a notation called LaTeX. For a formula in a sentence, put it between dollar signs:
+
+```markdown
+The area is $A = \pi r^2$.
+```
+
+For a formula on its own line, use two dollar signs above and below it:
+
+```markdown
+$$
+A = \pi r^2
+$$
+```
+
+## Show a code example
+
+If your talk includes programming, put the example between lines of three backticks. The language name helps mdeck color the code:
+
+````markdown
+```python
+print("Hello, everyone!")
+```
+````
+
+You can add `copy` to show a copy button. For JavaScript and Python, `live` adds a Run button and `editable` lets you change the example while presenting:
+
+````markdown
+```python live editable copy
+print(2 + 2)
+```
+````
+
+Live Python downloads its runtime the first time it runs, so it needs an internet connection. Live JavaScript runs in the presentation page itself, not in an isolated sandbox. Only run code you trust; a long-running example can make the presentation unresponsive.

package/docs/site/content/presenting.md

@@ -0,0 +1,93 @@
+# Add notes and present
+
+The presenter view puts your current slide, the next slide, your notes, and a timer in one place. Your audience can see the slides in a separate window.
+
+## Write notes for yourself
+
+Add a notes block at the end of a slide:
+
+```markdown
+# A place to grow
+
+Every neighborhood has a starting point.
+
+:::notes
+Welcome everyone. Ask who has visited the garden.
+
+- Pause for answers.
+- Keep this introduction short.
+:::
+```
+
+The words between `:::notes` and `:::` appear in the presenter view, not on the audience slide.
+
+The `write-slides` skill writes notes for every content slide. Make them yours before you present, by hand or by asking:
+
+```prompt
+Shorten the notes to cues I can glance at, and mark which slides I
+can skip if I run out of time.
+```
+
+## Open the presenter view
+
+```sh
+mdeck run my-talk.md
+```
+
+The launch page it opens has a **Presenter view** button.
+
+Use its audience-window button to open a separate view of the slides. If you have a projector or second screen, move that audience window onto it. Keep the presenter window on your own screen.
+
+The two windows follow the same slide and reveal position: navigate in either window and the other follows. This works between windows in the same browser and between your laptop and a paired iPad. To connect the iPad, see [Draw on your slides](drawing.html#present-from-an-ipad).
+
+Small icons next to **Speaker View** show what is connected to the deck: presenter views, audience windows and, for decks with polls, how many phones. Point at them to see on which devices, such as "Presenter view on an iPad". The launch page shows the same under **Present**, and marks each view that is open.
+
+For a single screen, switch the presenter view to its slide-only layout. **F** or the fullscreen button fills the screen in either the presenter view or the audience window; fullscreen does not select another view.
+
+To let people answer a question on their phones, put a poll on a slide. See [Ask your audience](audience.html).
+
+## Move through the talk
+
+| Key | What it does |
+|---|---|
+| Right arrow, Space, or Page Down | Show the next point, then the next slide |
+| Left arrow or Page Up | Hide the last revealed point, or return to the previous slide |
+| Home | Go to the first slide |
+| End | Go to the last slide when the slide view has focus |
+| R | Start again and clear the reveals |
+| D | Start or stop drawing on the slide ([Draw on your slides](drawing.html)) |
+| I | Hide or show the drawings |
+| F | Full screen, where the browser allows it |
+| N | Open or close the notes drawer, in the presenter view's slide-only layout |
+
+Click the slide area if your keys are not controlling it. Keys behave normally while you are typing in a text field.
+
+The timer is for your own reference; you can start, pause, and reset it in the presenter view.
+
+## Reveal points one at a time
+
+Wrap a list in a steps block:
+
+```markdown
+# Our plan
+
+:::steps
+- Meet the neighbors.
+- Choose a first project.
+- Set a date.
+:::
+```
+
+Each press of the next key reveals one point. Once all points are visible, the next press moves to the following slide. Printed slides show all the points.
+
+## Before the talk
+
+- Open the talk on the computer you will use.
+- Try the audience window and check the correct screen is showing.
+- Test every video, especially if it comes from the internet.
+- Run `mdeck check my-talk.md` to look for missing files or settings mistakes.
+- If the talk has a poll, scan its QR code with a phone in the room's network and vote once. Then reset the poll.
+
+## Are my notes private?
+
+Notes are hidden from the audience view, but a normal build includes them in the file, and someone with that file can inspect them. For a version to send around, use `mdeck send my-talk.md`, which removes the notes (see [Send, host or print your slides](sharing.html)).

package/docs/site/content/reusable-layouts.md

@@ -0,0 +1,74 @@
+# Use a reusable slide layout
+
+A reusable layout is a slide arrangement someone has made for a particular purpose: a comparison, a timeline, or a team introduction.
+
+You do not have to create a layout to use one. Someone, or an AI assistant, makes it once, and other people fill it with their own words. Your assistant sees every layout in the folder when it writes slides, so you can ask for one by name: “use the comparison layout for the before and after slide”.
+
+<!-- preview -->
+
+## Keep the layout with the talk
+
+If someone gives you a presentation folder with an `extensions` folder inside, keep that folder beside the slide file. mdeck finds those layouts automatically.
+
+```text
+my-talk/
+  my-talk.md
+  extensions/
+    comparison/
+      …files supplied by the layout's creator
+```
+
+Copy the whole layout folder if you move it to a different presentation. You do not need to edit mdeck itself. The same folder can also hold a theme or a set of colors made for your team; `mdeck list my-talk.md` lists everything it found.
+
+## See which layouts are available
+
+```sh
+mdeck list layouts my-talk.md
+```
+
+The list includes the usual layouts and any extra ones saved beside your talk.
+
+## Start from an example
+
+Ask mdeck to show the starting text for a layout:
+
+```sh
+mdeck starter comparison my-talk.md
+```
+
+Copy the text it prints into your slide file. Put `---` on its own line before it if you are adding it after an existing slide.
+
+Replace the example words, leaving the named areas and settings in place. If you use `mdeck new` to make a file beside an existing `extensions` folder, its wizard also offers those layouts.
+
+## Understand the comparison example
+
+The example shipped with this project contains two slides. The first uses an extra layout called `comparison`. The second uses the usual `split` layout with a list that appears one point at a time.
+
+Open it from the project folder:
+
+```sh
+mdeck run examples/custom-layouts/slides.md
+```
+
+The comparison slide has settings like these:
+
+```yaml
+layout: comparison
+props:
+  ratio: [2, 3]
+  emphasis: right
+```
+
+`props` groups this layout's options. The ratio gives a little more room to the right side. Changing `emphasis` to `left` moves the highlighted border to the left side. Use `none` for no highlighted side.
+
+The `:::slot left` and `:::slot right` blocks hold the words for the two sides. “Slot” simply means a named area that the layout knows how to arrange.
+
+## Check your changes
+
+```sh
+mdeck check my-talk.md
+```
+
+If a layout requires a particular area or setting, mdeck tells you when it is missing. The creator of each layout chooses its available settings, so one layout's options may not work in another.
+
+Want a new layout? Describe it to your assistant. The [advanced layout guide](custom-layouts.html) explains the code it writes.

package/docs/site/content/sharing.md

@@ -0,0 +1,88 @@
+# Send, host or print your slides
+
+The launch page that `mdeck run my-talk.md` opens has buttons for the three most common results: a folder to host, one file to send, and a PDF. The hosted folder and sent file open in the reader view and omit speaker notes. Each is made next to your slide file. The commands below do the same from the terminal and offer more options.
+
+| You want | Command | You get |
+|---|---|---|
+| One file to email | `mdeck send my-talk.md` | `my-talk.html`, opening in the reader view |
+| A folder for a website | `mdeck build my-talk.md --reader` | `dist/`, opening in the reader view, without notes |
+| A PDF | `mdeck pdf my-talk.md` | `my-talk.pdf` |
+
+## Send slides to someone
+
+The quickest way to give slides to people who were not in the room:
+
+```sh
+mdeck send my-talk.md
+```
+
+Send `my-talk.html` by email. It opens in a **reader view**: an outline of all slides on the left, the slides in the middle, a **Read** mode that stacks every slide for scrolling on a phone, a **Light**/**Dark** button, a **Download PDF** button, and a **Present** button that opens standalone slides. The PDF is inside the file, so there is nothing else to attach.
+
+- Drawings from `my-talk.drawings.json` are part of every build and PDF; `--no-drawings` leaves them out. See [Draw on your slides](drawing.html).
+- Your speaker notes are removed. Add `--notes` to keep them in the file, for example when you also present from the same file. Readers only see notes if you put `reader:` with `notes: true` in the settings at the top of your slide file.
+- The PDF is made while sending, using Chrome or Chromium on your computer. If neither is found, the button offers the browser's own "Save as PDF" dialog instead. Set `MDECK_CHROME` to the browser's path if it is installed somewhere unusual. `--no-pdf` skips it.
+- `-o` chooses the name: `mdeck send my-talk.md -o handout.html`.
+- The file keeps your theme and colours; readers can only switch between light and dark. To keep that fixed too, put `reader:` with `themes: false` in the settings at the top of your slide file.
+
+Anyone who opens a normal build can reach the reader view through the small **Overview** link in the corner, or by adding `?view=reader` to the address. [Views, commands and servers](views.html) lists every view. Likewise `?view=presenter` opens the presenter view of any build, as long as the notes were kept in the file.
+
+## Make a PDF on its own
+
+```sh
+mdeck pdf my-talk.md
+mdeck pdf my-talk.md -o handout.pdf
+```
+
+Each slide becomes one page at the slide's own size, with real text you can search and copy. Points that appear one at a time are all shown, and interactive slides such as diagrams that build up step by step appear finished. The reader's **Read** mode shows them the same way.
+
+A PDF is useful for reading or printing. Videos do not play in it, and interactive slides are shown in their finished state. A poll shows the answers it had when the PDF was made. You can also open a built presentation in your browser and choose **Print**, then **Save as PDF**; turn off the browser's own headers and footers if they appear.
+
+## Make a folder you can host
+
+While you write, mdeck reads your text file. To put the presentation on a website, **build** it: ask mdeck to make a browser-ready version of your talk.
+
+```sh
+mdeck build my-talk.md --reader
+```
+
+mdeck creates a folder called `dist`. It contains `index.html` and the local pictures, videos, and audio files the presentation uses.
+
+Send or upload the whole folder, not just `index.html`. You can compress the folder into a ZIP file first. This option is usually best for talks with large videos. `--reader` opens the reader view and removes speaker notes from the HTML. Add `--notes` to retain them; `reader.notes: true` also makes them visible. Without `--reader`, a normal build opens the deck view and retains notes.
+
+Building again updates the output. Keep your original slide file and pictures outside `dist`, because mdeck replaces the build output. `mdeck preview` shows the built folder in your browser.
+
+## Put the presentation on a website
+
+The built folder can be hosted as an ordinary static website. Upload its contents together so the relative image and video paths keep working. Every build contains every view; the address picks it: `?view=deck`, `?view=reader`, `?view=presenter` or `?view=audience`. Polls do not need the slides to be hosted; see [Ask your audience](audience.html#use-it-in-a-real-session).
+
+Building does not publish anything automatically. Uploading or deploying the files is a separate step with your hosting provider.
+
+## Make one HTML file of the presentation
+
+If you need the presentation itself, not the reader view, as a single file to transfer, use:
+
+```sh
+mdeck build my-talk.md --single-file -o my-talk.html
+```
+
+Here, `-o` means “save the result with this name.” The file contains the presentation and embedded local media. Videos become larger when embedded, so a folder is often more convenient for a video-heavy talk.
+
+The recipient can open the HTML file in a modern browser. External websites, online videos, and downloadable tools such as live Python still need a network connection. Fonts may look slightly different because this mode uses the theme's system-font alternatives.
+
+## Present without installing mdeck
+
+You can include small launchers with a folder build:
+
+```sh
+mdeck build my-talk.md --launchers
+```
+
+The folder then includes `present.sh` for macOS/Linux, and `present.bat` plus `present.ps1` for Windows. These start a local web server and open the presenter view. The other computer needs Python 3 and a modern browser.
+
+Use this with a folder build; it cannot be combined with `--single-file`.
+
+## Check before sending
+
+Open the final result, try its images and videos, and make sure the whole talk is there. If you expect to be offline, test without an internet connection.
+
+Remember that speaker notes are included in a normal build, even though they are hidden on the audience screen. `mdeck send` and `mdeck build --reader` remove them; remove anything confidential before building a public copy.

package/docs/site/content/theme-authoring.md

@@ -0,0 +1,144 @@
+# Create a theme or palette
+
+This guide describes the files behind a theme or palette. For the existing choices, see [Change the look](appearance.html).
+
+You do not need to write these files yourself. Describe the look to your assistant, and give it colours, fonts or a picture of a design you like:
+
+```prompt
+Make a theme for this deck in the style of our institute's poster:
+dark green backgrounds, a condensed sans-serif for headings, thin
+rules between sections. Keep it readable on a projector.
+```
+
+The rest of this page is the reference for what it writes, and for anyone comfortable with CSS who prefers to write it by hand.
+
+To look at the result and fine-tune it, run `mdeck design my-talk.md` (or `mdeck design` in a folder without a deck). It shows the theme or palette on a sample deck with every kind of slide, light and dark, and has forms for colours, fonts, sizes and spacing; see [Edit slides in your browser](editing.html). The files it writes are the ones described here.
+
+Someone may already have made what you need: `mdeck themes search` lists the theme repository, and [Install or share a theme](theme-repository.html) explains how to install a pack or share yours.
+
+Themes and palettes are **extensions**: each one is a folder with an `extension.toml` file that says what it is. Slide layouts use the same idea. Put the folder in `extensions/` beside your slide file and mdeck finds it automatically; there is nothing to register. The [extensions reference](extensions.html) has the complete list of settings.
+
+```text
+my-talk/
+  my-talk.md
+  extensions/
+    notebook/          a palette
+      extension.toml
+    calm/              a theme
+      extension.toml
+      styles.css
+```
+
+## Add a palette
+
+A palette is the quickest extension to make. It only needs a manifest, with every colour twice: for light and for dark slides.
+
+```toml
+schema = 1
+kind = "palette"
+id = "notebook"
+title = "Blue notebook"
+
+[light]
+"--bg" = "#ffffff"
+"--surface" = "#eef2f7"
+"--ink" = "#203148"
+"--ink-soft" = "#34465c"
+"--muted" = "#54647a"
+"--rule" = "#dbe3ee"
+"--accent" = "#2455c7"
+"--accent-2" = "#17625c"
+"--on-accent" = "#ffffff"
+
+[dark]
+"--bg" = "#0f1a2b"
+"--surface" = "#18263a"
+"--ink" = "#eef2f7"
+"--ink-soft" = "#c7d2e0"
+"--muted" = "#8fa0b6"
+"--rule" = "#24354d"
+"--accent" = "#7aa2ff"
+"--accent-2" = "#5ec4b6"
+"--on-accent" = "#0f1a2b"
+```
+
+The folder must be called `notebook` to match `id`. Use it with `palette: notebook` in your deck, and `appearance: dark` for the dark version. Colour names start with two dashes, so they are written in quotation marks. Dark slides get dark code colours and an inverted logo; check the result with the actual logo, since automatic inversion does not suit every image.
+
+`mdeck check` warns when two colours are too close to read, such as a pale accent on white.
+
+## The colours a theme may use
+
+| Colour | Purpose |
+|---|---|
+| `--bg` | Slide background |
+| `--surface` | Code and other raised surfaces |
+| `--ink` | Main text |
+| `--ink-soft` | Body text |
+| `--muted` | Secondary labels |
+| `--rule` | Borders |
+| `--accent` | Main highlight |
+| `--accent-2` | Secondary highlight |
+| `--on-accent` | Text placed on an accent background |
+
+A theme has no colours of its own: it uses these, and mixes of them, so every palette repaints it. For an inverted slide it uses the palette's other version, as `--inverse-bg`, `--inverse-ink`, `--inverse-accent` and so on:
+
+```css
+.slide--focus {
+  --bg: var(--inverse-bg);
+  --ink: var(--inverse-ink);
+  --accent: var(--inverse-accent);
+  background: var(--bg);
+  color: var(--ink);
+}
+```
+
+## Make a theme
+
+A theme has two files. The manifest holds the identity, fonts, its default palette, type and spacing, and the settings authors may change. The stylesheet holds the rules.
+
+```toml
+schema = 1
+kind = "theme"
+id = "calm"
+title = "Calm"
+description = "Soft sans-serif slides with plenty of space."
+palette = "notebook"          # the palette it uses unless the deck chooses one
+fonts = ["https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"]
+
+[tokens]
+"--fs-display" = "120px"
+"--fs-h" = "60px"
+"--fs-body" = "32px"
+"--pad-x" = "140px"
+"--pad-y" = "80px"
+"--font-display" = "\"Inter\", system-ui, sans-serif"
+"--font-body" = "\"Inter\", system-ui, sans-serif"
+
+[params.fontBody]
+token = "--font-body"
+title = "Body font"
+```
+
+`appearance = "dark"` makes the theme start dark. `palettes = ["notebook"]` limits it to the palettes listed, for a corporate design; a palette with `theme = "calm"` is then offered to this theme only.
+
+The easiest start is to copy a built-in theme from the framework's `assets/extensions/themes/` folder, rename the folder and `id`, and change the tokens. `styles.css` styles the slide frame and each layout class; the built-in stylesheets show which classes exist.
+
+mdeck writes the palette and the tokens into the page ahead of your stylesheet, so `styles.css` should only contain rules that refer to `var(--accent)` and the like. Do not repeat the values there.
+
+## Theme parameters
+
+Each `[params.name]` entry names a token authors may change under `params:` in their deck, such as a font:
+
+```yaml
+theme: calm
+params:
+  fontBody: "Georgia, serif"
+```
+
+Its default is simply the token's value. Colours are not parameters: they come from the palette.
+
+## Check every layout
+
+Try title, chapter, focus, image-text, split, full-bleed-image, and ordinary content slides. Include long titles, lists, pictures, code, footnotes, and both light and dark. Check each aspect ratio you intend to support and the browser's print output.
+
+`mdeck check my-talk.md` reports manifest mistakes with the file and setting name. `mdeck list my-talk.md` confirms that your theme or palette has been found.