mdeck 3.7.1 → 3.9.0

package/assets/extensions/themes/plain/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "plain"
 title = "Plain"
 description = "Black on white and lots of room: Inter, the heading in a column of its own beside the content, lists of short titles with a line under each, the accent only in small places; in greyscale, dark is the same, inverted."
-version = "0.1.0"
+version = "0.2.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -48,14 +48,20 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 [params.side]
 token = "--side"
 title = "Width of the heading column"
+type = "size"
+min = 400
+max = 640
+description = "560px of the 1920px slide by default, from about 400px to 640px; the content takes the rest."
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/plain/styles.css

@@ -27,7 +27,7 @@
 .slide-logo {
   position: absolute;
   top: var(--pad-y);
-  left: var(--pad-x);
+  inset-inline-start: var(--pad-x);
   height: 48px;
   width: auto;
   max-width: 280px;
@@ -153,25 +153,25 @@ strong { font-weight: 600; color: var(--ink); }
   grid-row: 1 / span 40;
   align-self: center;
   margin: 0;
-  padding-right: 24px;
+  padding-inline-end: 24px;
 }
 .slide-body > :last-child { margin-bottom: 0; }
 
 /* ─────────────────────────────────────────────
    LISTS — a short title with a line under it; plain lines otherwise
    ───────────────────────────────────────────── */
-.slide-body ul > li { line-height: 1.45; padding-left: 34px; }
+.slide-body ul > li { line-height: 1.45; padding-inline-start: 34px; }
 .slide-body ul > li::before {
   content: '\2013';
   position: absolute;
-  left: 0;
+  inset-inline-start: 0;
   top: 0;
   color: var(--muted);
 }
 /* An item that starts in bold: the bold part is a title on its own line,
    the rest a smaller description under it, and no marker. */
 .slide-body ul > li:has(> strong:first-child) {
-  padding-left: 0;
+  padding-inline-start: 0;
   font-size: calc(var(--fs-body) * 0.86);
   line-height: 1.45;
   color: var(--ink-soft);
@@ -184,11 +184,11 @@ strong { font-weight: 600; color: var(--ink); }
   color: var(--ink);
   margin-bottom: 4px;
 }
-.slide-body ol > li { line-height: 1.45; padding-left: 46px; }
+.slide-body ol > li { line-height: 1.45; padding-inline-start: 46px; }
 .slide-body ol > li::before {
   content: counter(slide-ol) '.';
   position: absolute;
-  left: 0;
+  inset-inline-start: 0;
   top: 0;
   font-variant-numeric: tabular-nums;
   color: var(--accent);
@@ -309,10 +309,10 @@ strong { font-weight: 600; color: var(--ink); }
   column-gap: 96px;
   align-content: center;
   align-items: start;
-  text-align: left;
+  text-align: start;
 }
 .slide--focus .slide-body:has(> .focus-eyebrow) > * { grid-column: 2; }
-.slide--focus .slide-body:has(> .focus-eyebrow) > .focus-eyebrow { grid-column: 1; grid-row: 1 / span 2; align-self: center; padding-right: 24px; }
+.slide--focus .slide-body:has(> .focus-eyebrow) > .focus-eyebrow { grid-column: 1; grid-row: 1 / span 2; align-self: center; padding-inline-end: 24px; }
 .slide--focus .slide-body:has(> .focus-eyebrow) .focus-content { align-items: flex-start; }
 .slide--focus .slide-body:has(> .focus-eyebrow) :is(.focus-statement, .focus-content h1, .focus-content p) {
   font-family: var(--font-body);
@@ -321,7 +321,7 @@ strong { font-weight: 600; color: var(--ink); }
   line-height: 1.4;
   letter-spacing: -0.005em;
   max-width: 900px;
-  text-align: left;
+  text-align: start;
 }
 
 /* ─────────────────────────────────────────────
@@ -368,7 +368,7 @@ strong { font-weight: 600; color: var(--ink); }
   column-gap: 80px;
   align-items: center;
 }
-.slide--split .split-heading { margin: 0; padding-right: 24px; }
+.slide--split .split-heading { margin: 0; padding-inline-end: 24px; }
 .slide--split .split-heading h1 { margin: 0; }
 .slide--split .slide-body:has(> .split-heading) .split-columns { align-self: stretch; }
 
@@ -402,7 +402,7 @@ strong { font-weight: 600; color: var(--ink); }
 .slide-body .callout {
   background: var(--surface);
   border: 0;
-  border-left: 3px solid var(--accent);
+  border-inline-start: 3px solid var(--accent);
   border-radius: 0 8px 8px 0;
   padding: 20px 28px 22px;
   margin: 0 0 16px;
@@ -416,9 +416,9 @@ strong { font-weight: 600; color: var(--ink); }
   color: var(--ink);
   margin: 0 0 4px 0;
 }
-.slide-body .callout p { padding-left: 0; margin: 0; color: var(--ink-soft); }
+.slide-body .callout p { padding-inline-start: 0; margin: 0; color: var(--ink-soft); }
 .slide-body .callout :is(.callout-title) { color: var(--ink); }
-.slide-body .callout:is(.callout-warning, .callout-caution) { border-left-color: var(--accent-3); }
+.slide-body .callout:is(.callout-warning, .callout-caution) { border-inline-start-color: var(--accent-3); }
 .slide-body .callout.callout-proof { background: none; border: 0; padding: 0; }
 
 /* ─────────────────────────────────────────────
@@ -444,7 +444,7 @@ strong { font-weight: 600; color: var(--ink); }
 .slide-body .code-block-wrapper { margin: 0 0 var(--gap-item); }
 
 .slide-body table { font-size: calc(var(--fs-body) * 0.9); font-variant-numeric: tabular-nums; }
-.slide-body :is(th, td) { padding: 12px 24px 12px 0; }
+.slide-body :is(th, td) { padding-block: 12px; padding-inline: 0 24px; }
 .slide-body th { font-weight: 600; color: var(--ink); border-bottom: 1px solid var(--ink); }
 .slide-body td { border-bottom: 1px solid var(--rule); }
 
@@ -464,7 +464,7 @@ strong { font-weight: 600; color: var(--ink); }
    FOOTNOTES, MATH, AUDIENCE QUESTIONS
    ───────────────────────────────────────────── */
 .slide-footnotes, .slide-citations { font-family: var(--font-body); }
-.slide .katex-display { font-size: var(--fs-sub); margin: 24px 0; overflow-x: auto; overflow-y: hidden; text-align: left; }
+.slide .katex-display { font-size: var(--fs-sub); margin: 24px 0; overflow-x: auto; overflow-y: hidden; text-align: start; }
 .slide .poll-track, .slide .scale-track { border-radius: 4px; background: var(--surface); }
 .slide .poll-fill, .slide .scale-fill { border-radius: 4px; background: var(--accent); }
-.slide .question-cards li { border-radius: 8px; border-left: 0; background: var(--surface); }
+.slide .question-cards li { border-radius: 8px; border-inline-start: 0; background: var(--surface); }

package/assets/extensions/themes/work/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "work"
 title = "Work"
 description = "An everyday company template: IBM Plex Sans, an accent band along the top, the logo top left, headings in a fixed place, section dividers with a large number in the accent, a quiet footer with the page number."
-version = "0.1.0"
+version = "0.2.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -47,14 +47,20 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 [params.band]
 token = "--band"
-title = "Height of the band along the top (0px for none)"
+title = "Height of the band along the top"
+type = "size"
+min = 0
+max = 32
+description = "14px by default, up to about 32px; 0px leaves the top without a band."
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/work/styles.css

@@ -15,8 +15,8 @@
   content: '';
   position: absolute;
   top: 0;
-  left: 0;
-  right: 0;
+  inset-inline-start: 0;
+  inset-inline-end: 0;
   height: var(--band);
   background: var(--accent);
   z-index: 3;
@@ -47,7 +47,7 @@
 .slide-logo {
   position: absolute;
   top: var(--pad-y);
-  left: var(--pad-x);
+  inset-inline-start: var(--pad-x);
   height: 72px;
   width: auto;
   max-width: 360px;
@@ -181,29 +181,29 @@ strong { font-weight: 600; color: var(--ink); }
 /* ─────────────────────────────────────────────
    LISTS — square bullets, numbers in the accent
    ───────────────────────────────────────────── */
-.slide-body ul > li { line-height: 1.4; padding-left: 40px; }
+.slide-body ul > li { line-height: 1.4; padding-inline-start: 40px; }
 .slide-body ul > li::before {
   content: '';
   position: absolute;
-  left: 2px;
+  inset-inline-start: 2px;
   top: calc(0.7em - 6px);
   width: 12px;
   height: 12px;
   background: var(--accent);
 }
 /* A point inside a point: a dash. */
-.slide-body li ul > li { padding-left: 34px; }
+.slide-body li ul > li { padding-inline-start: 34px; }
 .slide-body li ul > li::before {
   top: calc(0.7em - 1.5px);
   width: 16px;
   height: 3px;
   background: var(--muted);
 }
-.slide-body ol > li { line-height: 1.4; padding-left: 52px; }
+.slide-body ol > li { line-height: 1.4; padding-inline-start: 52px; }
 .slide-body ol > li::before {
   content: counter(slide-ol) '.';
   position: absolute;
-  left: 0;
+  inset-inline-start: 0;
   top: 0;
   font-weight: 600;
   font-variant-numeric: tabular-nums;
@@ -238,7 +238,7 @@ strong { font-weight: 600; color: var(--ink); }
 .slide--title.has-image .title-image {
   position: absolute;
   top: 0;
-  right: 0;
+  inset-inline-end: 0;
   bottom: 0;
   width: 40%;
   height: 100%;
@@ -248,7 +248,7 @@ strong { font-weight: 600; color: var(--ink); }
 }
 .slide--title.has-image .slide-header > span:last-child:not(.brand) { visibility: hidden; }
 /* The footer's hairline stops short of the picture (40% of 1920px, and a gap). */
-:is(.slide--title, .slide--chapter).has-image .slide-footer { margin-right: 712px; }
+:is(.slide--title, .slide--chapter).has-image .slide-footer { margin-inline-end: 712px; }
 
 /* ─────────────────────────────────────────────
    LAYOUT: CHAPTER — a section divider: the number in the accent, a broader band
@@ -262,7 +262,7 @@ strong { font-weight: 600; color: var(--ink); }
   letter-spacing: -0.04em;
   font-variant-numeric: tabular-nums;
   color: var(--accent);
-  margin: 0 0 40px -6px;
+  margin-block: 0 40px; margin-inline: -6px 0;
 }
 .chapter-meta {
   font-family: var(--font-body);
@@ -298,7 +298,7 @@ strong { font-weight: 600; color: var(--ink); }
 .slide--chapter.has-image .chapter-image {
   position: absolute;
   top: 0;
-  right: 0;
+  inset-inline-end: 0;
   bottom: 0;
   width: 40%;
   height: 100%;
@@ -319,14 +319,14 @@ strong { font-weight: 600; color: var(--ink); }
   letter-spacing: 0.1em;
   text-transform: uppercase;
   color: var(--accent);
-  margin: 0 0 32px 58px;
+  margin-block: 0 32px; margin-inline: 58px 0;
 }
 .focus-content {
   display: flex;
   flex-direction: column;
   align-items: flex-start;
-  border-left: 10px solid var(--accent);
-  padding: 6px 0 10px 48px;
+  border-inline-start: 10px solid var(--accent);
+  padding-block: 6px 10px; padding-inline: 48px 0;
 }
 .focus-statement,
 .slide--focus .focus-content h1,
@@ -345,7 +345,7 @@ strong { font-weight: 600; color: var(--ink); }
   font-family: var(--font-body);
   font-size: var(--fs-body);
   color: var(--muted);
-  margin: 32px 0 0 58px;
+  margin-block: 32px 0; margin-inline: 58px 0;
 }
 
 /* ─────────────────────────────────────────────
@@ -386,8 +386,8 @@ strong { font-weight: 600; color: var(--ink); }
    ───────────────────────────────────────────── */
 .split-columns { gap: 0; }
 .slide--split :is(.split-left, .split-right) { padding: 0 56px; }
-.slide--split .split-left { padding-left: 0; border-right: 1px solid var(--rule); }
-.slide--split .split-right { padding-right: 0; }
+.slide--split .split-left { padding-inline-start: 0; border-inline-end: 1px solid var(--rule); }
+.slide--split .split-right { padding-inline-end: 0; }
 
 /* ─────────────────────────────────────────────
    LAYOUT: FULL-BLEED IMAGE — the title on a label at the lower left
@@ -407,8 +407,8 @@ strong { font-weight: 600; color: var(--ink); }
   letter-spacing: -0.015em;
   color: var(--ink);
   background: var(--bg);
-  border-left: 10px solid var(--accent);
-  padding: 28px 44px 32px 40px;
+  border-inline-start: 10px solid var(--accent);
+  padding-block: 28px 32px; padding-inline: 40px 44px;
   margin: 0;
   max-width: 1300px;
   text-wrap: balance;
@@ -433,7 +433,7 @@ strong { font-weight: 600; color: var(--ink); }
   --bar: var(--accent);
   background: var(--surface);
   border: 0;
-  border-left: 8px solid var(--bar);
+  border-inline-start: 8px solid var(--bar);
   border-radius: 0 4px 4px 0;
   padding: 22px 32px 24px;
   margin: 14px 0 0;
@@ -447,7 +447,7 @@ strong { font-weight: 600; color: var(--ink); }
   text-transform: uppercase;
   margin: 0 0 8px 0;
 }
-.slide-body .callout p { padding-left: 0; margin: 0; color: var(--ink); }
+.slide-body .callout p { padding-inline-start: 0; margin: 0; color: var(--ink); }
 .slide-body :is(.callout-note, .callout-tip, .callout-important) { --bar: var(--accent); }
 .slide-body :is(.callout-warning, .callout-caution) { --bar: var(--accent-3); }
 .slide-body .callout-definition { --bar: var(--accent-2); }
@@ -479,7 +479,7 @@ strong { font-weight: 600; color: var(--ink); }
 .slide-body blockquote {
   position: relative;
   margin: 0 0 var(--gap-item);
-  padding: 0 0 0 64px;
+  padding-block: 0; padding-inline: 64px 0;
   border: 0;
   max-width: 1300px;
   font-size: calc(var(--fs-body) * 1.1);
@@ -490,7 +490,7 @@ strong { font-weight: 600; color: var(--ink); }
 .slide-body blockquote::before {
   content: '\201C';
   position: absolute;
-  left: 0;
+  inset-inline-start: 0;
   top: -0.12em;
   font-family: var(--font-display);
   font-size: 104px;
@@ -503,7 +503,7 @@ strong { font-weight: 600; color: var(--ink); }
    FOOTNOTES, MATH, AUDIENCE QUESTIONS
    ───────────────────────────────────────────── */
 .slide-footnotes, .slide-citations { font-family: var(--font-body); }
-.slide .katex-display { font-size: var(--fs-sub); margin: 32px 0; overflow-x: auto; overflow-y: hidden; text-align: left; }
+.slide .katex-display { font-size: var(--fs-sub); margin: 32px 0; overflow-x: auto; overflow-y: hidden; text-align: start; }
 .slide .poll-track, .slide .scale-track { border-radius: 2px; background: var(--surface); }
 .slide .poll-fill, .slide .scale-fill { border-radius: 2px; background: var(--accent); }
-.slide .question-cards li { border-radius: 4px; border-left: 6px solid var(--accent); background: var(--surface); }
+.slide .question-cards li { border-radius: 4px; border-inline-start: 6px solid var(--accent); background: var(--surface); }

package/docs/reference/authoring.md

@@ -60,25 +60,31 @@ Each `---` line starts a new slide. Frontmatter is only needed when you want a s
 | `session.id` | from the title | Name the session code is derived from |
 | `session.code` | from `session.id` | The session code itself, 4 to 8 digits; phones join at `<server>/<code>` |
 | `components` | — | Extra folders of Preact components shared between decks, relative to the deck or starting with `~/` |
-| `params` | — | Theme-specific color/font overrides (see below) |
+| `params` | — | The theme's own settings, such as its fonts (see below) |
 | `reader.themes` | `true` | Whether the reader view offers a switch between light and dark (see below) |
 | `reader.notes` | `false` | Whether the reader view shows speaker notes under each slide in Read mode |
 | `bibliography` | — | Reference file, or a list of them, relative to the deck: `.bib`, `.json` (CSL-JSON) or `.yml` (Hayagriva) (see [Citations](#citations-and-references)) |
 | `csl` | `apa` | Citation style: `apa`, `vancouver`, `harvard1`, or a `.csl` file |
 | `nocite` | — | References to list without citing them; `['*']` lists the whole file |
 | `show.citations` | `true` | `false` leaves out each slide's own references above the footer |
+| `hotspots` | `off` | Number keys zoom in on parts of a slide while presenting: `auto` (pictures, code, tables, formulas, videos, callouts, columns, polls and `data-hotspot` elements), `marked` (only `data-hotspot` elements) or `off` (1–9 go to slides) |
 
 ### Theme params
 
-Some themes expose their fonts as settings. Set them under `params:`:
+Themes offer settings of their own: their fonts, and often the size or
+strength of what makes them look the way they do. Set them under `params:`:
 
 ```yaml
 params:
   fontDisplay: "Georgia, serif"
+  glassBlur: 12px
 ```
 
-Available params depend on the theme; `mdeck list themes` shows them. Colours
-are not params: they come from the palette.
+Available params depend on the theme; `mdeck list themes` shows them with the
+kind of value each takes: a size in pixels, a number, a switch (`1` or `0`), a
+choice or a font. `0` or `0px` turns a feature off. A value that does not fit
+is left out, and `mdeck check` says why. Colours are not params: they come from
+the palette.
 
 ---
 
@@ -162,6 +168,7 @@ description: A short description shown under the title.
 | `layout` | Slide layout (see below) |
 | `section` | Section label shown in the slide header (auto-propagated — see below) |
 | `title` | Name in the outline and reader navigation, for slides without a heading (not shown on the slide) |
+| `hotspots` | This slide's own hotspots: `auto`, `marked`, `off` or `false` (see the deck field) |
 
 ### Section labels
 
@@ -537,6 +544,16 @@ A title written after the type on the `:::` line still wins over both.
 
 The presenter view, the launch page and the editor are tools for the author and always stay English.
 
+### One talk in several languages
+
+Write the talk once per language, in files named for it, side by side: `talk.en.md`, `talk.de.md`, `talk.hi.md` and so on. The language is a two-letter code after the name, with a region if needed (`talk.de-CH.md`). A file named this way needs no `lang`: its name gives it.
+
+`mdeck run talk.en.md` finds the other files with the same name and adds a **Language** switch to the presenter view (**L** goes to the next language). Switching changes the slides, your notes and mdeck's own words in every window: the audience window, a paired iPad and the phones following the talk. Your place stays, as do the step on the slide, the drawings and the poll results: slides match by their place in the deck, so keep the same slides in the same order in every language. A deck in one language shows no switch.
+
+A language written from right to left, such as Farsi (`fa`), Arabic or Hebrew, sets its slides and your notes from right to left: the text, lists, quotations, tables and the place of the header and the page number. Code and maths stay left to right, as do mdeck's own controls.
+
+Each file is a complete deck: `mdeck check`, `mdeck edit` and `mdeck send` work on one language at a time, and drawings and results are kept beside the file you run.
+
 To change single words, name them under `labels`:
 
 ```yaml

package/docs/reference/extensions.md

@@ -201,7 +201,11 @@ Keep headings to a few words; three or four points make a good slide.
   `: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.
+  written twice. `type` (`size`, `number`, `switch`, `choice` or `font`) says
+  what kind of value it takes; `min`, `max` and `step` go with a size (in
+  pixels) or a number, `choices` with a choice. The token's value must be of
+  that type. The editor shows a slider, a box to tick or a list for it, and
+  `mdeck check` reports a deck value that does not fit.
 - `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

package/docs/reference/themes.md

@@ -77,8 +77,12 @@ params:
   fontDisplay: "Georgia, serif"
 ```
 
-A parameter's default is its token's value. Unknown parameter names are
-reported by `mdeck check`.
+A parameter's default is its token's value. `type` says what kind of value it
+takes: `size` (pixels, with `min`, `max` and `step`), `number` (with the same
+three), `switch` (1 or 0), `choice` (one of `choices`) or `font`. A deck value
+that does not fit is left out, and `mdeck check` reports it, like unknown
+parameter names; one outside `min` and `max` is used, with a warning. Without
+a `type`, a parameter takes any text.
 
 Optional settings: `description`, `appearance = "dark"` for a theme that starts
 dark, and `palettes = [...]` to offer only those palettes (a corporate design

package/docs/site/content/drawing.md

@@ -14,7 +14,7 @@ Press **D** in standalone slides or in the presenter view, or use the pen button
 | Laser pointer | A red dot with a white core and a short trail that disappears by itself, for pointing at something. With a pencil that can hover, the dot follows it without touching. Never kept. |
 | Eraser | Removes whole strokes you touch. |
 
-**Zoom**: two fingers zoom into the slide and move around it, one finger moves a zoomed slide, and Ctrl + scroll (a trackpad pinch) zooms on a laptop. Only the slide grows; the bars and the toolbar keep their size. The audience window shows the same part of the slide. **1:1** at the top left shows the whole slide again, as does the next slide.
+**Zoom**: two fingers zoom into the slide and move around it, one finger moves a zoomed slide, and Ctrl + scroll (a trackpad pinch) zooms on a laptop. Only the slide grows; the bars and the toolbar keep their size. The audience window shows the same part of the slide. **1:1** at the top left shows the whole slide again, as does the next slide. To zoom straight to a picture or a table with a number key, see [hotspots](presenting.html#zoom-in-on-part-of-a-slide).
 
 On a touch screen such as an iPad, drawing is on as soon as the presenter view opens, and in the deck as soon as the pencil touches it, with the toolbar folded into its button in the bottom right corner (↘ folds it again). Until then, a tap on the right third of the screen goes forward, on the left third back, and a swipe does the same. Drawing starts with the laser pointer; choose the pen or the highlighter to write. The pen and the highlighter each have colours and three sizes, and each keeps its own; one pen colour is **Accent**, the accent colour of the theme and palette: a drawing in it changes with them. The other pen colours follow light and dark: on dark slides red, blue and green are lighter, and the text colour is white instead of black. The toolbar also has undo and redo (also Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z), **Clear this slide**, and **×** to stop drawing; **D** and **Escape** do the same. While you draw, the pencil and the mouse draw; fingers keep working: a swipe to the left goes forward, to the right back, a tap on a stroke selects it, and buttons and polls on the slide still respond. Turn slides with the arrow keys or the presenter view's arrows, as always. Holding the pen still for half a second at the end of a stroke makes it a straight line; near a multiple of 15° (horizontal, vertical, 45° …) it snaps to that angle.
 

package/docs/site/content/presenting.md

@@ -61,11 +61,56 @@ To let people answer a question on their phones, put a poll on a slide. See [Ask
 | 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 |
+| L | Switch to the talk's next language, for a talk written in several (see below) |
+| 1–9 | Zoom in on a part of the slide, with hotspots on (see below); without them, go to slide 1–9 |
+| 0 or Escape | Show the whole slide again |
+| H | Turn hotspots on or off for this talk, in the presenter view |
 
 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.
 
+## Zoom in on part of a slide
+
+Hotspots let you show one part of a slide large: a picture, a chart, a code block, a table. Turn them on in the deck's settings:
+
+```markdown
+---
+hotspots: auto
+---
+```
+
+The presenter view then puts a small numbered key on each part of the slide you can zoom to. Press its number, or tap the key on an iPad, and the slide zooms smoothly until that part fills the screen. A part of another shape than the screen keeps the slide around it in view. The audience window, a paired iPad and phones following the talk zoom along; only the presenter view shows the keys.
+
+To see the whole slide again, press the same number again, **0** or **Escape**, tap the slide, or use **1:1**. The next point or the next slide shows the whole slide by itself, so you never need an extra key press to move on. Another number while zoomed goes straight to that part.
+
+| Setting | What gets a key |
+|---|---|
+| `hotspots: auto` | Pictures, code blocks, tables, formulas, videos, callouts, columns and polls, and anything marked `data-hotspot` |
+| `hotspots: marked` | Only what you marked with `data-hotspot`; nothing is found by itself |
+| `hotspots: off` | Nothing. This is the default: 1–9 go to slides 1–9 |
+
+A slide can have its own setting in its frontmatter, such as `hotspots: false` for a slide whose numbers you do not want, or `hotspots: auto` on one slide of a deck without hotspots. Mark a part of your own in inline HTML with `data-hotspot`, and keep a found one out with `data-hotspot="off"`:
+
+```markdown
+The rate is <span data-hotspot>**2.4 %** a year</span>, for now.
+```
+
+Parts that nearly fill the slide, or its whole width, get no key, since there is nothing to zoom; what is inside them may. A part inside another one shares its key: a column with a formula and a tip in it is one part. The keys follow reading order, up to nine on a slide. In the editor, the deck's settings and each slide's details have a **Hotspots** choice too. **H**, or the button beside **Draw**, turns hotspots on or off for the rest of the talk without changing the deck; a slide set to `false` stays without them.
+
+## One talk in several languages
+
+To give a talk in English, German or another language as the room needs, write it once per language, in files side by side named for it:
+
+```text
+talk.en.md
+talk.de.md
+```
+
+Start either with `mdeck run talk.en.md`: the presenter view gets a **Language** switch, and **L** goes to the next language. Switching changes the slides, your notes and the words mdeck shows in every window, including the audience window, a paired iPad and phones following along, and keeps your place, the step on the slide and the drawings. Slides match by their place in the deck, so keep the same slides in the same order in every file. A talk in one language shows no switch.
+
+`mdeck send talk.de.md` makes the German file to hand out; each file is a complete deck of its own.
+
 ## Reveal points one at a time
 
 Wrap a list in a steps block:

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

@@ -140,6 +140,34 @@ params:
 
 Its default is simply the token's value. Colours are not parameters: they come from the palette.
 
+Say what kind of value a parameter takes with `type`, so mdeck can check what authors write and the editor can offer the right control:
+
+```toml
+[params.bar]
+token = "--bar"
+title = "Thickness of the bar under headings"
+type = "size"
+min = 0
+max = 20
+description = "12px by default, from about 6px to 20px; 0px leaves headings without bars."
+```
+
+| `type` | Takes | The editor shows | Settings |
+|---|---|---|---|
+| `size` | pixels: `12px`, or just `12` | a slider | `min`, `max`, `step` in pixels |
+| `number` | a number; a strength from 0 to 1 | a slider | `min`, `max`, `step` |
+| `switch` | `1` or `0` (also `true`/`false`, `on`/`off`) | a box to tick | |
+| `choice` | one of its `choices` | a list | `choices = ["left", "right"]` |
+| `font` | a CSS font list | a text box | |
+
+The token's value must be a value of that type: a `size` is written `"12px"`, a `switch` `"1"`. A value in the deck that does not fit is left out, and the theme's own value stays; `mdeck check` says why. A value outside `min` and `max` is used, with a warning: the range is what the theme was made for. A parameter without a `type` takes any text, as before.
+
+A few habits make parameters easy to use:
+
+- Turn a feature off with its parameter at zero (`0px`, `0`) rather than a second parameter.
+- Use a switch or a strength by multiplying with it, as in `calc(330px * var(--shapes))`.
+- Let the `description` give the default and a sensible range: the editor shows it under the control, and assistants read it.
+
 ## Say what it is for
 
 A `[guide]` tells people, and assistants that write slides, what your theme is good for and how slides for it are written: