mdeck 3.10.1 → 3.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +15 -4
  3. package/assets/base.css +6 -1
  4. package/docs/reference/authoring.md +111 -9
  5. package/docs/site/assets/site.css +2 -0
  6. package/docs/site/content/appearance.md +1 -1
  7. package/docs/site/content/audience.md +36 -8
  8. package/docs/site/content/commands.md +6 -3
  9. package/docs/site/content/drawing.md +5 -5
  10. package/docs/site/content/getting-started.md +2 -32
  11. package/docs/site/content/install.md +49 -0
  12. package/docs/site/content/media.md +20 -1
  13. package/docs/site/content/presenting.md +67 -9
  14. package/docs/site/content/sharing.md +1 -0
  15. package/docs/site/content/welcome.md +21 -1
  16. package/docs/site/content/writing.md +27 -0
  17. package/docs/site/images/features/hotspots.webp +0 -0
  18. package/docs/site/images/features/languages.webp +0 -0
  19. package/docs/site/pages.js +1 -0
  20. package/examples/custom-layouts/slides.md +21 -9
  21. package/examples/showcase/refs.bib +21 -0
  22. package/examples/showcase/slides.ar.drawings.json +11 -0
  23. package/examples/showcase/slides.ar.md +567 -0
  24. package/examples/showcase/slides.de.drawings.json +11 -0
  25. package/examples/showcase/slides.de.md +567 -0
  26. package/examples/showcase/slides.de.results.json +57 -0
  27. package/examples/showcase/slides.en.drawings.json +11 -0
  28. package/examples/showcase/{slides.md → slides.en.md} +112 -5
  29. package/package.json +1 -1
  30. package/skills/write-slides/SKILL.md +14 -2
  31. package/src/build/check.js +34 -7
  32. package/src/build/components.js +5 -3
  33. package/src/build/config.js +2 -0
  34. package/src/build/homePlugin.js +64 -14
  35. package/src/build/include.js +249 -0
  36. package/src/build/inkPlugin.js +12 -2
  37. package/src/build/relayAccess.js +3 -1
  38. package/src/build/renderCheck.js +23 -3
  39. package/src/build/slidesPlugin.js +70 -22
  40. package/src/build/svgCheck.js +65 -0
  41. package/src/build/timingPlugin.js +96 -0
  42. package/src/cli/args.js +6 -5
  43. package/src/cli/index.js +77 -21
  44. package/src/components/Bibliography.jsx +7 -2
  45. package/src/components/Poll.jsx +2 -2
  46. package/src/components/QrCodeTag.jsx +2 -2
  47. package/src/components/VideoPlayer.jsx +6 -1
  48. package/src/components/WordCloud.jsx +7 -6
  49. package/src/components/activity.jsx +11 -8
  50. package/src/components/poll.css +2 -0
  51. package/src/core/editDeck.js +44 -7
  52. package/src/core/icons.js +9 -1
  53. package/src/core/labels.js +78 -0
  54. package/src/core/parseSlides.js +16 -6
  55. package/src/core/reactions.js +27 -0
  56. package/src/core/resultsReport.js +153 -0
  57. package/src/core/source.js +8 -1
  58. package/src/core/timing.js +83 -0
  59. package/src/core/validateDeck.js +11 -2
  60. package/src/editor/components/DeckSettings.jsx +1 -0
  61. package/src/editor/components/MetaFields.jsx +1 -0
  62. package/src/home/Home.jsx +39 -93
  63. package/src/home/home.css +5 -17
  64. package/src/layouts/layoutApi.jsx +51 -8
  65. package/src/layouts/renderSlide.jsx +13 -1
  66. package/src/live/answer/answer.css +9 -0
  67. package/src/live/answer/answer.js +32 -4
  68. package/src/live/client.js +23 -4
  69. package/src/live/rooms.js +18 -6
  70. package/src/runtime/KeyHelp.jsx +115 -0
  71. package/src/runtime/PresenterChrome.jsx +168 -0
  72. package/src/runtime/Reactions.jsx +56 -0
  73. package/src/runtime/RehearsalSummary.jsx +129 -0
  74. package/src/runtime/component.js +27 -0
  75. package/src/runtime/deck-stage.js +371 -37
  76. package/src/runtime/helpKeys.js +75 -0
  77. package/src/runtime/ink/bus.js +13 -5
  78. package/src/runtime/ink/outbox.js +27 -0
  79. package/src/runtime/ink/room.js +37 -12
  80. package/src/runtime/ink/segments.js +21 -0
  81. package/src/runtime/main.jsx +508 -286
  82. package/src/runtime/shared.js +77 -0
  83. package/src/runtime/slideControls.js +60 -0
  84. package/src/runtime/steps.js +36 -0
  85. package/src/runtime/useTalkTimer.js +67 -0
  86. package/examples/citations/refs.bib +0 -30
  87. package/examples/citations/refs.yml +0 -21
  88. package/examples/citations/slides.md +0 -43
  89. package/examples/citations/slides.pdf +0 -0
  90. package/examples/poll/slides.md +0 -127
  91. package/examples/showcase/slides.drawings.json +0 -11
@@ -0,0 +1,49 @@
1
+ # Install mdeck
2
+
3
+ Three commands in a terminal, a few minutes in all. mdeck is published on npm, the package registry for JavaScript tools, as [mdeck](https://www.npmjs.com/package/mdeck).
4
+
5
+ A terminal is an app where you type short commands: Terminal on macOS, or PowerShell on Windows. A text editor may also have a Terminal menu.
6
+
7
+ ## 1. Install Node.js
8
+
9
+ mdeck runs on [Node.js](https://nodejs.org) 22 or newer, which brings npm along. Check whether you have it:
10
+
11
+ ```sh
12
+ node --version
13
+ ```
14
+
15
+ A number of 22 or higher is enough. If the command is not found or the number is lower, install the LTS version from [nodejs.org](https://nodejs.org).
16
+
17
+ ## 2. Install mdeck
18
+
19
+ ```sh
20
+ npm install -g mdeck
21
+ ```
22
+
23
+ Check that it is ready:
24
+
25
+ ```sh
26
+ mdeck --help
27
+ ```
28
+
29
+ ## 3. Teach your AI assistant
30
+
31
+ ```sh
32
+ mdeck skill --install claude
33
+ ```
34
+
35
+ This installs a *skill*: instructions that tell your assistant how mdeck slides are written, which layouts and looks exist, and how to check its work. Write `codex`, `cursor`, `copilot` or `gemini` instead of `claude` for those assistants; for Cursor, Copilot and Gemini, run it in your talk's folder. `mdeck skill` shows the list, and [Work with an AI assistant](claude-skill.html) says more.
36
+
37
+ Then [make your first presentation](getting-started.html).
38
+
39
+ ## Update, check or remove
40
+
41
+ | To | Run |
42
+ |---|---|
43
+ | Update to the newest version | `npm install -g mdeck` |
44
+ | See which version you have | `npm list -g mdeck` |
45
+ | Remove mdeck | `npm uninstall -g mdeck` |
46
+
47
+ What each version brings is in the [changelog](https://github.com/tilman-schieber/mdeck/blob/main/CHANGELOG.md) and the [releases](https://github.com/tilman-schieber/mdeck/releases). After an update, run `mdeck skill --install claude` again, so your assistant knows the new features.
48
+
49
+ If `npm` or `mdeck` is not found, see [When something goes wrong](troubleshooting.html#the-command-is-not-recognized).
@@ -59,7 +59,7 @@ For a cropped picture, use `fit: cover`. You can add `position: "left center"` o
59
59
 
60
60
  ## Pictures that follow the theme
61
61
 
62
- 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`.
62
+ 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`, `--accent-3` and `--on-accent`.
63
63
 
64
64
  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:
65
65
 
@@ -68,6 +68,25 @@ Draw an SVG title picture for this talk that uses the palette's
68
68
  colours, with a transparent background, and put it on the title slide.
69
69
  ```
70
70
 
71
+ ### A drawing that builds up
72
+
73
+ Such a drawing is part of the slide, so its parts can appear one at a time, like the points of a list. Put each part in a group and number it with `data-step`: the parts appear in the order of their numbers, and parts with the same number appear together.
74
+
75
+ ```html
76
+ <g data-step="1">…the first box…</g>
77
+ <g data-step="1">…the second box…</g>
78
+ <g data-step="2">…the arrow between them…</g>
79
+ ```
80
+
81
+ The numbers decide the order, not where a part is in the file, so an arrow can be drawn under the boxes and still appear after them. With hotspots on (see [Zoom in on part of a slide](presenting.html#zoom-in-on-part-of-a-slide)), `data-hotspot` on a group gives it a key of its own. The same drawing can be on several slides; each copy keeps its arrowheads and gradients.
82
+
83
+ `mdeck check` looks at these drawings: it names colours that stay fixed in dark mode, palette names without a colour after the comma, and styles that would reach the rest of the slide. An assistant can do all of it for you:
84
+
85
+ ```prompt
86
+ Draw the three stages of the pipeline as an SVG in the palette's colours
87
+ that builds up one stage at a time, and make each stage a hotspot.
88
+ ```
89
+
71
90
  ## Add a video file
72
91
 
73
92
  Paste this line into a normal slide, or into one side of a split slide:
@@ -34,17 +34,20 @@ can skip if I run out of time.
34
34
  mdeck run my-talk.md
35
35
  ```
36
36
 
37
- The launch page it opens has a **Presenter view** button.
37
+ The launch page it opens has a **Presenter view** button. The presenter view shows the slide with a toolbar under it, and beside it the time, the next slide and your notes:
38
38
 
39
- 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.
39
+ - **Under the slide**: previous and next, then drawing, black screen, all slides, hotspots and full screen, and **This slide**: what can be done on the slide shown, such as a poll's lock, results and right answer, or playing its video. Point at a button to see what it does and its key; **?** lists all keys.
40
+ - **At the top of the notes**: the slide number (type one to jump there), the timer, the audience window button (a projector), the icons of who is connected, and the settings.
41
+ - **Who is connected** (the icons): the audience windows, a paired iPad, phones; the join link for polls; and the codes that pair an iPad or a phone. A red dot means something needs you, such as phones that do not follow.
42
+ - **Settings**: the layout (speaker, slide only, phone clicker), the theme, palette and light or dark to try, the language, the timer and rehearsal, the size of the notes, and the way back to the launch page.
43
+
44
+ Open the audience window with the projector button. If you have a projector or second screen, move it there, and keep the presenter view on your own screen.
40
45
 
41
46
  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).
42
47
 
43
48
  A video file you play, pause or move in the presenter view does the same in the audience window, which plays the sound; the presenter view's copy stays silent while the audience window is open. Click the audience window once before the talk, so the browser lets it play sound.
44
49
 
45
- 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.
46
-
47
- 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.
50
+ For a single screen, choose **Slide only** in the settings. **F** or the fullscreen button fills the screen in either the presenter view or the audience window; fullscreen does not select another view.
48
51
 
49
52
  To let people answer a question on their phones, put a poll on a slide. See [Ask your audience](audience.html).
50
53
 
@@ -57,18 +60,71 @@ To let people answer a question on their phones, put a poll on a slide. See [Ask
57
60
  | Home | Go to the first slide |
58
61
  | End | Go to the last slide when the slide view has focus |
59
62
  | R | Start again and clear the reveals |
63
+ | B or . | Make the audience's screen black, and show the slide again (see below) |
64
+ | J | Show the join code over the slide, on every screen, and hide it again, in the presenter view of a deck with polls ([Ask your audience](audience.html)) |
65
+ | O | Show all slides in a grid, to pick one (see below) |
60
66
  | D | Start or stop drawing on the slide ([Draw on your slides](drawing.html)) |
61
67
  | I | Hide or show the drawings |
62
68
  | F | Full screen, where the browser allows it |
63
69
  | N | Open or close the notes drawer, in the presenter view's slide-only layout |
64
70
  | L | Switch to the talk's next language, for a talk written in several (see below) |
65
- | 1–9 | Zoom in on a part of the slide, with hotspots on (see below); without them, go to slide 1–9 |
71
+ | 1–9 | Zoom in on a part of the slide, with hotspots on (see below); without them, nothing |
66
72
  | 0 or Escape | Show the whole slide again |
67
73
  | H | Turn hotspots on or off for this talk, in the presenter view |
74
+ | T | Start or pause the timer, in the presenter view |
75
+ | ? | Show the keys that work at this moment, over the slide; **?** again or Escape closes the list |
76
+
77
+ ## Use your phone as a clicker
78
+
79
+ Start `mdeck run my-talk.md --network`, open the presenter view, click the connection icons at its top, choose **Phone clicker**, and scan the code with the phone's camera. The phone shows the slide small, the time and how you stand against the plan, your notes in large print, and big **Previous** and **Next** buttons where your thumb is. Under the slide it has the slide's own controls: close a poll, show its results or the right answer, play a video, zoom into a numbered part. The audience window on the laptop does what the phone does. Nothing on the phone draws. Where the browser allows it (`https://`, or a page on the laptop itself), the phone's screen stays on during the talk.
80
+
81
+ The clicker is one of the presenter view's layouts: the settings switch any presenter view between **Speaker**, **Slide only** and **Clicker**, on the phone as well. Each device remembers its layout.
82
+
83
+ ## Black out the screen
84
+
85
+ Press **B** when the room should look at you, not at the slide: the audience window goes black, and so do a paired iPad's audience window and phones following the talk. Your presenter view keeps the slide under a dark veil and says that the audience sees a black screen. **B** again, the next key (→, Space) or a click on the black screen shows the slide again, without moving on. Many presentation clickers have a button for this; it sends a full stop, which works like **B**. The presenter view also has a button for it.
86
+
87
+ ## Find a slide
88
+
89
+ Press **O**, or the button with the row of slides, to see every slide of the talk in a grid: the slide shown has a red frame. Move with the arrow keys and press Enter, or click a slide, to go there. **O** or Escape closes the grid and leaves you where you were. In the presenter view the grid opens in your own slide, so the audience keeps the slide they are looking at until you pick another. Every slide in the grid shows all of its points, to make it easier to recognise.
90
+
91
+ To jump to a slide, tap or click the slide number in the presenter view (beside the arrows on an iPad, at the top of the speaker layout), type the number and press Enter, or Go on an iPad's keyboard. Escape keeps the current slide.
68
92
 
69
93
  Click the slide area if your keys are not controlling it. Keys behave normally while you are typing in a text field.
70
94
 
71
- The timer is for your own reference; you can start, pause, and reset it in the presenter view.
95
+ The timer is for your own reference; you can start, pause (**T**), and reset it in the presenter view. It keeps running through a reload of the page.
96
+
97
+ ## Time your talk
98
+
99
+ Give a slide the time you want to spend on it with `time:` in its settings, and the whole talk a length with `time:` in the deck's settings:
100
+
101
+ ```markdown
102
+ ---
103
+ time: 20m
104
+ ---
105
+
106
+ ---
107
+ :::meta
108
+ time: 2m
109
+ :::
110
+ # The results
111
+ ```
112
+
113
+ Write times as `90s`, `2m`, `1m30s` or `1.5m`. Slides without a time share what the deck's time leaves over; without a deck time, they get none.
114
+
115
+ Once the deck has times, the presenter view shows under the timer how much time is left on the slide (amber in its last 15 seconds, red once it is over), the length of the talk, and whether you are ahead of or behind your plan. In the slide-only layout the time left on the slide sits beside the timer.
116
+
117
+ ### Rehearse
118
+
119
+ You do not have to guess the times. Rehearse the talk and mdeck measures them:
120
+
121
+ ```bash
122
+ mdeck rehearse my-talk.md
123
+ ```
124
+
125
+ This opens the presenter view rehearsing: the timer starts, and every second on a slide counts towards it, including when you come back to it. **Rehearse** in the presenter view's settings, and the tile on the launch page, start a rehearsal too. Press **Finish**, or go on past the last slide, and a table shows for each slide the time it has, the time you spent and the new time, rounded to 15 seconds. Change a new time in 15-second steps with **−** and **+** (or **↑** and **↓** on its row), put back the time the slide had, or take the slide's time out. **Save to deck** writes the new times into the slides' settings, so you can see them in the file and change them like any other setting. The open windows do not reload, and the deck is copied to `.mdeck-backups/` first.
126
+
127
+ Saving needs `mdeck run` or `mdeck rehearse`. A deck you built can still rehearse; **Copy** gives you the times to paste in yourself.
72
128
 
73
129
  ## Zoom in on part of a slide
74
130
 
@@ -88,7 +144,7 @@ To see the whole slide again, press the same number again, **0** or **Escape**,
88
144
  |---|---|
89
145
  | `hotspots: auto` | Pictures, code blocks, tables, formulas, videos, callouts, columns and polls, and anything marked `data-hotspot` |
90
146
  | `hotspots: marked` | Only what you marked with `data-hotspot`; nothing is found by itself |
91
- | `hotspots: off` | Nothing. This is the default: 1–9 go to slides 1–9 |
147
+ | `hotspots: off` | Nothing. This is the default: the number keys do nothing |
92
148
 
93
149
  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"`:
94
150
 
@@ -96,6 +152,8 @@ A slide can have its own setting in its frontmatter, such as `hotspots: false` f
96
152
  The rate is <span data-hotspot>**2.4 %** a year</span>, for now.
97
153
  ```
98
154
 
155
+ In a drawing that takes its colours from the theme, `data-hotspot` on a group makes that part of the drawing a hotspot.
156
+
99
157
  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.
100
158
 
101
159
  ## One talk in several languages
@@ -125,7 +183,7 @@ Wrap a list in a steps block:
125
183
  :::
126
184
  ```
127
185
 
128
- 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.
186
+ 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. A drawing can build up the same way; see [A drawing that builds up](media.html#a-drawing-that-builds-up).
129
187
 
130
188
  ## Before the talk
131
189
 
@@ -21,6 +21,7 @@ Send `my-talk.html` by email. It opens in a **reader view**: an outline of all s
21
21
  - Drawings from `my-talk.drawings.json` are part of every build and PDF; `--no-drawings` leaves them out. Readers can hide them with the **Drawings** button in the reader view. See [Draw on your slides](drawing.html).
22
22
  - 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.
23
23
  - Slides with a poll, question, word cloud or scale stay as a record of the talk: the question and its options, marked as answered live. Add `--no-polls` to leave them out of the file and its PDF, together with slides showing the join code (`<qrcode join />`).
24
+ - `--slide 12-30` sends only some slides, for example the part of a deck shown in today's lecture. The numbers are the slides' places in the deck, as `mdeck check --render` and `mdeck snapshot` count them, and may be listed, `3,5-7`. Drawings stay on their slides, and a `<style>` written on a slide that is left out still applies. A deck `time:` shrinks to what the kept slides were planned to take.
24
25
  - 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.
25
26
  - `-o` chooses the name: `mdeck send my-talk.md -o handout.html`.
26
27
  - 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.
@@ -4,7 +4,7 @@ Bring what you already have: old PowerPoint slides, a PDF, a Word document, a pa
4
4
 
5
5
  The content stays yours. The assistant works from your material, not from its own idea of the topic: it chooses layouts, tidies wording, moves detail into speaker notes and checks the file. You do not need to know how to program. The slides are a plain text file, so you can read every word, change any of it yourself, or ask for something different.
6
6
 
7
- [Make your first presentation](getting-started.html)
7
+ [Make your first presentation](getting-started.html) [Install mdeck](install.html)
8
8
 
9
9
  ## What you can do with it
10
10
 
@@ -32,6 +32,26 @@ Polls, scales, word clouds, open questions and numbers to guess. People scan the
32
32
 
33
33
  <section>
34
34
 
35
+ [![The projector zoomed in on a table, and in front of it the presenter view showing the same slide with numbered keys on its code, table and formula](images/features/hotspots.webp)](images/features/hotspots.webp)
36
+
37
+ ### Zoom into a chart, a table or a line of code
38
+
39
+ Turn on hotspots, and the presenter view puts a number on each picture, table, formula and code block. Press it, or tap it on an iPad, and the slide glides in until that part fills the projector; press it again to see the whole slide. Phones following the talk zoom along, and the audience never sees the numbers. [Zoom in on part of a slide](presenting.html#zoom-in-on-part-of-a-slide)
40
+
41
+ </section>
42
+
43
+ <section>
44
+
45
+ [![The same slide with a Python example in English, German, Hindi and Farsi, the Farsi one running right to left](images/features/languages.webp)](images/features/languages.webp)
46
+
47
+ ### Give the talk in the room's language
48
+
49
+ Keep the talk once per language, `talk.en.md` beside `talk.de.md`, and press **L** to switch in the middle of it: the slides, your notes and every screen change at once, and you stay on the same slide and step. Farsi, Arabic and Hebrew run right to left, with code and formulas left to right. [One talk in several languages](presenting.html#one-talk-in-several-languages)
50
+
51
+ </section>
52
+
53
+ <section>
54
+
35
55
  [![A slide with author–year citations and the full references at its foot, next to a slide that lists all references](images/features/citations.webp)](images/features/citations.webp)
36
56
 
37
57
  ### Cite your sources properly
@@ -107,6 +107,33 @@ Keep the spaces before `title` and `author`: they put those values inside the `m
107
107
 
108
108
  For a talk in German, add `lang: de` to these settings. The page is then marked as German, which helps screen readers and hyphenation, and the words mdeck adds for your audience, such as the buttons for readers and polls, are German too.
109
109
 
110
+ ## Put several files together
111
+
112
+ A course, or a talk built from parts you also give on their own, can be one deck made of others. A slide with nothing but an `:::include` line stands for all the slides of another file:
113
+
114
+ ```markdown
115
+ ---
116
+ theme: neue
117
+ meta:
118
+ title: "Algorithms, autumn term"
119
+ ---
120
+
121
+ ---
122
+ # Welcome
123
+
124
+ ---
125
+ :::include ./lectures/01-sorting.md
126
+
127
+ ---
128
+ :::include ./lectures/02-graphs.md slides=3-7
129
+ ```
130
+
131
+ Each included file stays a deck of its own: `mdeck run lectures/02-graphs.md` still presents it alone, with its own theme and settings. Included, its slides come along with what they need: its references, its components, its own callout names, its hotspots setting and its time, which its slides share as they do when it is shown alone. The look (theme, palette, size, language) is that of the deck that includes it. A file of slides without settings of its own can be included too. `slides=3-7` (or `slides=2`, `slides=1,4-6`) keeps some of them, numbered as that file shows them.
132
+
133
+ Pictures, videos and drawings in an included file are found from its own folder, wherever it lies. A deck in another language takes the included file in that language where there is one: `course.de.md` including `./lectures/02-graphs.md` shows `02-graphs.de.md` beside it. An included file may include others.
134
+
135
+ Edit the slides of an included file in that file. The editor shows the include as one card naming the file, and while `mdeck run` is open, a change to that file appears in the deck straight away. Times saved after a rehearsal go into the file each slide is written in. `mdeck check` checks every file, and names the file and line of a problem.
136
+
110
137
  ## Reading older examples
111
138
 
112
139
  Older decks put slide settings between `---` lines too:
@@ -1,5 +1,6 @@
1
1
  export const pages = [
2
2
  { slug: 'index', title: 'Welcome to mdeck', group: 'Start here', file: 'welcome.md', description: 'Turn your existing slides, documents and notes into a deck with an AI assistant, then present and share it.', preview: 'first-talk' },
3
+ { slug: 'install', title: 'Install mdeck', group: 'Start here', file: 'install.md', description: 'Install Node.js and mdeck from npm, teach your AI assistant, and keep mdeck up to date.' },
3
4
  { slug: 'getting-started', title: 'Make your first presentation', group: 'Start here', file: 'getting-started.md', description: 'Set up mdeck and your AI assistant, hand over your material, and open the deck it makes.' },
4
5
  { slug: 'claude-skill', title: 'Work with an AI assistant', group: 'Start here', source: '../reference/claude-skill.md', description: 'Set up Claude Code, Codex, Cursor, Copilot or Gemini, turn PowerPoint, PDF, Word or notes into a deck, and change it by asking.' },
5
6
  { slug: 'writing', title: 'Read and adjust your slides', group: 'Make your presentation', file: 'writing.md', description: 'The simple marks in a slide file, so you can read what your assistant wrote and fix small things.' },
@@ -25,7 +25,7 @@ props:
25
25
  ## Single HTML file
26
26
 
27
27
  :::tip
28
- Useful when transferring one file is operationally important.
28
+ Handy when one file is easier to pass on than a folder.
29
29
  :::
30
30
 
31
31
  - All local assets embedded
@@ -33,7 +33,7 @@ Useful when transferring one file is operationally important.
33
33
  :::
34
34
 
35
35
  :::notes
36
- This layout is loaded from extensions/comparison beside this deck.
36
+ This layout is not built into mdeck: it comes from `extensions/comparison/` beside this deck. `ratio` sets the widths of the two sides, `emphasis` which one stands out.
37
37
  :::
38
38
 
39
39
  ---
@@ -41,20 +41,32 @@ This layout is loaded from extensions/comparison beside this deck.
41
41
  layout: split
42
42
  id: built-in-regions
43
43
  props:
44
- ratio: [1, 2]
44
+ ratio: [1, 1]
45
45
  :::
46
- # Built-in layouts use the same region model
46
+ # A layout of your own
47
47
 
48
48
  :::slot left
49
- ```js
50
- const template = 'comparison'
49
+ ```markdown
50
+ :::meta
51
+ layout: comparison
52
+ props:
53
+ emphasis: right
54
+ :::
55
+ # Deployment options
56
+ :::slot left
57
+ ## Directory bundle
58
+ :::
51
59
  ```
52
60
  :::
53
61
 
54
62
  :::slot right
55
63
  :::steps
56
- - Define a manifest.
57
- - Write a Preact layout.
58
- - Use it from Markdown.
64
+ - `extension.toml` names the layout, its areas and its settings.
65
+ - `layout.jsx` places the areas, `styles.css` styles them.
66
+ - A slide chooses it with `layout: comparison`.
59
67
  :::
60
68
  :::
69
+
70
+ :::notes
71
+ All three files are in `extensions/comparison/`. `mdeck list layouts` shows the deck's own layouts beside mdeck's, and `mdeck starter comparison` prints a slide to start from. To use the layout in other decks, install it once for all of them; the guide "Reusable layouts" shows how.
72
+ :::
@@ -0,0 +1,21 @@
1
+ @article{roediger2006,
2
+ author = {Roediger, Henry L. and Karpicke, Jeffrey D.},
3
+ title = {Test-Enhanced Learning: Taking Memory Tests Improves Long-Term Retention},
4
+ journal = {Psychological Science},
5
+ year = {2006},
6
+ volume = {17},
7
+ number = {3},
8
+ pages = {249--255},
9
+ doi = {10.1111/j.1467-9280.2006.01693.x}
10
+ }
11
+
12
+ @article{freeman2014,
13
+ author = {Freeman, Scott and Eddy, Sarah L. and McDonough, Miles and Smith, Michelle K. and Okoroafor, Nnadozie and Jordt, Hannah and Wenderoth, Mary Pat},
14
+ title = {Active Learning Increases Student Performance in Science, Engineering, and Mathematics},
15
+ journal = {Proceedings of the National Academy of Sciences},
16
+ year = {2014},
17
+ volume = {111},
18
+ number = {23},
19
+ pages = {8410--8415},
20
+ doi = {10.1073/pnas.1319030111}
21
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "version": 1,
3
+ "width": 1920,
4
+ "height": 1080,
5
+ "slides": {
6
+ "draw-on-any-slide": [
7
+ {"id":"tour:underline","tool":"pen","color":"#e11d48","size":7,"points":[[1253,489,0.45],[1267,491,0.48],[1280,493,0.52],[1293,494,0.55],[1307,495,0.58],[1320,496,0.61],[1333,496,0.64],[1347,495,0.66],[1360,494,0.68],[1373,492,0.7],[1387,491,0.72],[1400,489,0.73],[1413,487,0.74],[1427,486,0.75],[1440,485,0.75],[1453,485,0.75],[1467,486,0.74],[1480,487,0.73],[1493,488,0.72],[1507,490,0.71],[1520,492,0.69],[1533,494,0.67],[1547,496,0.64],[1560,497,0.62],[1573,498,0.59],[1587,499,0.56],[1600,499,0.53],[1613,498,0.49],[1627,497,0.46],[1640,495,0.43],[1653,494,0.39],[1667,492,0.36],[1680,491,0.33],[1693,489,0.3],[1707,489,0.27],[1720,488,0.25],[1733,489,0.22],[1747,489,0.2],[1760,491,0.19],[1773,493,0.17],[1787,495,0.16]]},
8
+ {"id":"tour:circle","tool":"pen","color":"#e11d48","size":6,"points":[[1690,520,0.5],[1694,520,0.54],[1699,520,0.57],[1703,521,0.6],[1707,523,0.64],[1711,526,0.66],[1714,529,0.69],[1716,533,0.71],[1718,537,0.73],[1719,541,0.74],[1720,545,0.75],[1719,549,0.75],[1718,553,0.75],[1716,557,0.74],[1714,561,0.73],[1711,563,0.71],[1708,566,0.69],[1704,568,0.66],[1701,570,0.63],[1697,571,0.6],[1693,572,0.57],[1689,572,0.54],[1685,572,0.5],[1681,572,0.46],[1677,570,0.43],[1673,569,0.4],[1670,567,0.36],[1667,564,0.34],[1664,560,0.31],[1662,557,0.29],[1660,552,0.27],[1660,548,0.26],[1660,544,0.25],[1661,539,0.25],[1663,535,0.25],[1665,532,0.26],[1668,529,0.27],[1671,526,0.29],[1675,524,0.31],[1679,523,0.34],[1683,522,0.37],[1687,522,0.4],[1691,522,0.43],[1695,522,0.47],[1699,524,0.5],[1703,525,0.54]]}
9
+ ]
10
+ }
11
+ }