mdeck 2.3.0 → 3.1.0

package/docs/reference/extensions.md

@@ -211,32 +211,46 @@ 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.
+## Installed themes and palettes
+
+Every theme and palette can be installed on its own, as a package. mdeck looks
+for them in this order: its own (`assets/extensions/`, minus those removed
+with `mdeck themes remove` or `mdeck palettes remove`, listed in
+`~/.mdeck/removed.json` as `theme:<id>` or `palette:<id>`), the user's folder
+(`~/.mdeck/extensions`, or `$MDECK_HOME/extensions`), and the `extensions/`
+folder beside the deck. For themes and palettes a later place replaces an
+earlier one with the same id: an installed newer version replaces the built-in
+one, and a deck's own copy replaces both (with a warning when it replaces one
+installed for every deck). Layouts are built in and may not be replaced;
+within one place an id may appear only once per kind.
+
+A theme or palette meant to be installed carries a few more settings in its
+`extension.toml`: `version` (`1.0.0`), `author`, `license`, `homepage`, and
+`mdeck = ">=X.Y.Z"`, the oldest mdeck it works with. What it needs follows
+from its settings: a theme needs its default `palette`, and a palette with
+`theme = "<id>"` needs that theme. Installing one installs what it needs;
+removing a palette is refused while an installed theme uses it by default, and
+removing a theme removes the palettes that belong only to it.
+
+`mdeck themes install <theme>` and `mdeck palettes install <palette>` install
+for every deck, into `themes/<id>/` or `palettes/<id>/` in the user's folder;
+given a slide file, a folder or `--local`, into the `extensions/` folder
+beside the deck (what it needs too, unless it is built in). Installing a
+built-in one for every deck offers it again. A package holds 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-package.json` with its kind, id,
+version, source and a checksum of every file; `update` and `remove` refuse to
+touch files changed since then unless given `--force`.
+
+The repository serves `catalogue.json` (`{ schema: 2, themes: [...],
+palettes: [...] }`, each with its id, version, default palette or theme,
+`url`, `sha256`, `preview`, and `builtIn` for those that come with mdeck) and
+one JSON file per version holding the text of its files.
+`mdeck themes build <repository> -o <out> [--check]` writes both from a
+folder with `themes/` and `palettes/`; `MDECK_THEMES_URL` points mdeck at
+another catalogue. Without a connection, mdeck offers its built-in ones.
 
 ## Listing what is available
 

package/docs/reference/palettes.md

@@ -9,7 +9,7 @@ Every palette is a family with two variants, **light** and **dark**. A deck choo
 ```yaml
 ---
 theme: neue
-palette: terra        # optional; without it the theme's default palette
+palette: nordic       # optional; without it the theme's default palette
 appearance: dark      # optional: light or dark; without it the theme's default
 ---
 ```
@@ -20,21 +20,17 @@ The presenter view and the reader view switch palette and light or dark without
 
 | 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 |
+| `lagoon` | teal on warm stone, orange second accent | deep teal-black, bright teal |
+| `paper` | off-white paper and near-black ink with one orange accent | charcoal with a softer orange |
 
 `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.
+Each theme names a default: neue uses `swiss`, academic `nordic`, aurora `neon`.
+
+More palettes are in the [theme repository](https://github.com/tilman-schieber/mdeck-themes). The palettes cobalt, terra, phosphor, pastel and forest, built in before mdeck 3.0, are there; installing the theme duet, editorial, terminal or sketch brings its palette along. Graphite and ember were removed because the built-in nordic and paper look almost the same; a deck that names them is told which to use. Install one with `mdeck palettes install <palette> my-talk.md`.
 
 ## Colours
 
@@ -90,7 +86,7 @@ description = "Sea blue and rust on chalk white."
 
 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`.
+`theme = "my-theme"` makes a palette private: only that theme offers it, as a corporate design theme does with its own colours.
 
 ## Readability
 
@@ -103,4 +99,4 @@ Colour names start with dashes, so quote them as TOML keys. A dark variant also
 | 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.
+The built-in palettes meet these in both variants. A private palette may use its accent only as a surface (a corporate yellow, say), so its accents are not checked as text.

package/docs/reference/themes.md

@@ -18,15 +18,16 @@ theme: neue
 |---|---|---|
 | `neue` | Swiss style: large flush-left type, rules, red on white | `swiss` |
 | `aurora` | Northern lights: curtains of light, night-sky chapters, frosted glass | `neon` |
-| `duet` | Two voices: heavy slab headings, split slides as two colour fields, diagonal chapters | `cobalt` |
-| `editorial` | Magazine spread: masthead rule, drop caps, pull quotes, Roman chapter numerals | `terra` |
-| `fhnw` | The FHNW corporate design | `brand` (the only one) |
-| `terminal` | A terminal session: prompts, a blinking cursor, a tmux status bar | `phosphor`, dark |
+| `minimal` | Nothing but the content: system fonts, calm type, no decoration; works offline | `paper` |
 | `academic` | A lecture: compact type, the heading fixed at the top and the content centred below, theorem and definition blocks, booktabs tables, a footnote rule | `nordic` |
-| `sketch` | A sketchbook: handwriting on dotted paper, marker scribbles, sticky-note callouts, taped photos | `pastel` |
 
 `mdeck list my-talk.md` lists them with their descriptions.
 
+More themes are in the [theme repository](https://github.com/tilman-schieber/mdeck-themes):
+`mdeck themes search` lists them, and `mdeck themes install <theme> my-talk.md`
+puts one beside the deck, with its default palette. The themes duet, editorial,
+fhnw, terminal and sketch, built in before mdeck 3.0, are there.
+
 ## Theme structure
 
 ```text
@@ -78,8 +79,8 @@ A parameter's default is its token's value. Unknown parameter names are
 reported by `mdeck check`.
 
 Optional settings: `description`, `appearance = "dark"` for a theme that starts
-dark, and `palettes = [...]` to offer only those palettes (the FHNW theme offers
-only `brand`). `[files] styles` may name one stylesheet or a list.
+dark, and `palettes = [...]` to offer only those palettes (a corporate design
+theme can offer only its own palette). `[files] styles` may name one stylesheet or a list.
 
 ### `styles.css`
 

package/docs/site/content/appearance.md

@@ -27,14 +27,10 @@ If you already have a settings block there, change the existing lines rather tha
 |---|---|
 | `neue` | Swiss style: large type, clear lines, red on white |
 | `aurora` | Northern lights: curtains of light, night-sky chapters and glass |
-| `duet` | Two voices: two accent colours that take turns, slab headings |
-| `editorial` | A magazine spread: serif headlines, drop caps, pull quotes |
-| `fhnw` | The FHNW visual identity |
-| `terminal` | A terminal session: headings typed at a prompt, a blinking cursor, a status bar |
+| `minimal` | Nothing but the content: system fonts, calm type, no decoration; works offline |
 | `academic` | A lecture: compact slides, theorem and definition boxes, tables like in a paper |
-| `sketch` | A sketchbook: handwriting, marker scribbles, sticky notes; a chalkboard in the dark |
 
-Each theme comes with colours that suit it, so you do not have to choose any.
+Each theme comes with colours that suit it, so you do not have to choose any. More themes are in the theme repository (see “Themes that moved to the repository” below).
 
 ## See the themes
 
@@ -52,41 +48,17 @@ Default colours: `swiss`.
 
 Default colours: `neon`.
 
-### Duet
-
-[![The tour's title slide in the Duet theme](images/themes/duet.webp)](images/themes/duet.webp)
-
-Default colours: `cobalt`.
-
-### Editorial
-
-[![The tour's title slide in the Editorial theme](images/themes/editorial.webp)](images/themes/editorial.webp)
-
-Default colours: `terra`.
-
-### FHNW
-
-[![The tour's title slide in the FHNW theme](images/themes/fhnw.webp)](images/themes/fhnw.webp)
-
-Default colours: its own FHNW colours.
-
-### Terminal
-
-[![The tour's title slide in the Terminal theme](images/themes/terminal.webp)](images/themes/terminal.webp)
-
-Default colours: `phosphor`, dark.
-
 ### Academic
 
 [![The tour's title slide in the Academic theme](images/themes/academic.webp)](images/themes/academic.webp)
 
 Default colours: `nordic`.
 
-### Sketch
+### Minimal
 
-[![The tour's title slide in the Sketch theme](images/themes/sketch.webp)](images/themes/sketch.webp)
+[![The tour's title slide in the Minimal theme](images/themes/minimal.webp)](images/themes/minimal.webp)
 
-Default colours: `pastel`.
+Default colours: `paper`. It uses the fonts already on the computer, so it needs no internet connection and looks plain on purpose.
 
 ## Choose colours
 
@@ -94,27 +66,19 @@ To use other colours, set `palette` to one of these:
 
 | Name to use | Colours |
 |---|---|
-| `lagoon` | Teal on warm stone |
 | `swiss` | White, black and signal red (neue's own) |
-| `cobalt` | Strong ultramarine on white |
-| `nordic` | Ice grey, deep navy and a cool steel blue |
-| `graphite` | Black and white with a steel-blue accent |
-| `terra` | Cream, deep navy and brick red |
-| `forest` | Deep green with moss and ochre |
-| `ember` | Sand and espresso with orange |
-| `neon` | Violet and magenta, loud |
-| `phosphor` | Green on black, like an old terminal screen |
-| `pastel` | Soft pastels, mauve and peach (in the style of Catppuccin) |
+| `nordic` | Ice grey, deep navy and a cool steel blue (academic's own) |
+| `neon` | Violet and magenta, loud (aurora's own) |
+| `lagoon` | Teal on warm stone |
+| `paper` | Off-white and near-black with one orange accent (minimal's own) |
 
 ```yaml
 ---
 theme: neue
-palette: terra
+palette: paper
 ---
 ```
 
-The FHNW theme always uses the FHNW colours.
-
 ## Light or dark
 
 Every palette has a light and a dark version. Choose dark for a dark lecture hall, light for a bright room:
@@ -122,7 +86,7 @@ Every palette has a light and a dark version. Choose dark for a dark lecture hal
 ```yaml
 ---
 theme: neue
-palette: terra
+palette: nordic
 appearance: dark
 ---
 ```
@@ -131,7 +95,7 @@ Some slides use the other version on purpose: neue's statement slides are dark i
 
 ## Every theme in every palette
 
-The first chapter slide of the tour in each palette a theme offers. Choose a theme above the pictures; click a sheet to see it larger. The FHNW theme has only its own colours, so it is not shown here.
+The first chapter slide of the tour in each palette a theme offers. Choose a theme above the pictures; click a sheet to see it larger. A theme that offers only its own colours is not shown here.
 
 Some themes turn their chapter slides around on purpose: aurora's are a night sky in a light talk, and light in a dark one.
 
@@ -155,7 +119,29 @@ Its theme, palette and light or dark controls, under the notes, let you try othe
 
 ## More themes from other people
 
-The theme repository has themes and palettes others made. `mdeck themes search` lists them, and `mdeck themes install <pack> my-talk.md` puts one beside your slides; see [Install or share a theme](theme-repository.html).
+The themes above come with mdeck. The theme repository has more: `mdeck themes search` and `mdeck palettes search` list them, and `mdeck themes install <theme>` installs one for all your decks, with its palette. You can also remove the ones you never use; see [Install, remove or share a theme](theme-repository.html).
+
+### Themes that moved to the repository
+
+Earlier versions of mdeck came with more themes and palettes. They are now in the theme repository:
+
+| Theme | What it looks like (its palette) |
+|---|---|
+| `duet` | Two accent colours that take turns, slab headings (`cobalt`) |
+| `editorial` | A magazine spread with serif headlines and pull quotes (`terra`) |
+| `fhnw` | The FHNW visual identity, with its own `brand` palette only |
+| `terminal` | Headings typed at a prompt, a status bar; it starts dark (`phosphor`) |
+| `sketch` | Handwriting, marker scribbles, sticky notes (`pastel`) |
+
+The palette `forest` is there too: `mdeck palettes install forest`.
+
+The palettes `graphite` and `ember` were removed: use `nordic` or `paper`, which come with mdeck and look almost the same.
+
+A deck that still names one of them stops with a message that tells you what to install, for example:
+
+```sh
+mdeck themes install duet
+```
 
 ## Add your name and organization
 

package/docs/site/content/commands.md

@@ -12,7 +12,8 @@ For how the commands, the views and the servers fit together, see [Views, comman
 | `mdeck new` | Make a presentation with guided questions |
 | `mdeck run my-talk.md` | Open the launch page: present, edit, check and send from one place; slides reload when you save |
 | `mdeck edit my-talk.md` | Edit slides, colors and themes in the browser; saves to the file |
-| `mdeck themes search`, `install <pack>`, `remove`, `update`, `list` | Themes and palettes from the theme repository; see [Install or share a theme](theme-repository.html) |
+| `mdeck themes search`, `install <theme>`, `remove`, `update`, `list` | Themes: install more (each with its palette), remove the ones you do not use; see [Install, remove or share a theme](theme-repository.html) |
+| `mdeck palettes search`, `install <palette>`, … | The same for palettes |
 | `mdeck design [my-talk.md or folder]` | Look at themes and palettes on a sample deck and fine-tune them; saves to `extensions/` |
 | `mdeck migrate my-talk.md --dry-run` | Preview the changes needed for API 2.0 |
 | `mdeck check my-talk.md` | Check settings and look for missing local files |
@@ -31,7 +32,7 @@ For how the commands, the views and the servers fit together, see [Views, comman
 
 - **Preview:** a small live copy of the deck to flip through; click it to open the audience window at that slide.
 - **Present:** the presenter view, audience window and reader view, each in a new tab. The presenter view has notes, drawing controls, a timer and next-slide preview; switch to its slide-only layout for a single screen. The audience window shows slides without notes. Fullscreen is a control inside either view, not a separate view.
-- **Write and learn:** the visual editor and these guides. Each starts the first time you click it.
+- **Write and learn:** the visual editor, the theme editor (themes and palettes on a sample deck, see [Install, remove or share a theme](theme-repository.html)) and these guides. Each starts the first time you click it.
 - **Send:** buttons that make the `dist` folder, one file to send, or a PDF, next to your slide file, and show them in your file manager.
 - **Polls:** for a deck with polls: the server (built in, or the `server` setting and whether it answers), the join link and session code for phones, and for a server of your own the key that lets your browser move the phones along and reset polls (see below).
 - **Check:** the same problems `mdeck check` reports, such as missing pictures.

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

@@ -14,7 +14,7 @@ The rest of this page is the reference for what it writes, and for anyone comfor
 
 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.
+Someone may already have made what you need: `mdeck themes search` lists the theme repository, and [Install, remove or share a theme](theme-repository.html) explains how to install one 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.
 

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

@@ -1,76 +1,88 @@
-# Install or share a theme
+# Install, remove or share a theme
 
-Besides the themes and palettes that come with mdeck, other people share theirs in the **theme repository**: <https://github.com/tilman-schieber/mdeck-themes>. A shared theme or palette comes as a **pack**: one theme with the palettes made for it, or a set of palettes.
+mdeck comes with four themes, `neue`, `academic`, `aurora` and `minimal`, and five palettes, `swiss`, `nordic`, `neon`, `paper` and `lagoon`. They work right away, also without an internet connection. More themes and palettes are in the **theme repository**; try every one on a sample deck, light and dark, at <https://gh.tschieber.de/mdeck-themes/>.
 
 ## Find and install one
 
-See what there is:
+Themes and palettes each have their own command, with the same words:
 
 ```sh
 mdeck themes search
 mdeck themes search warm
+mdeck palettes search
 ```
 
-Install a pack beside your slides:
+Install a theme:
 
 ```sh
-mdeck themes install solarized my-talk.md
+mdeck themes install duet
 ```
 
-It is copied into the `extensions` folder next to `my-talk.md`, like a theme you made yourself, so the slide folder keeps working on any computer. Then choose it in the deck settings (`palette: solarized`) or in the editor's **Deck** tab.
+A theme comes with its default palette, so this installs the palette `cobalt` too. A palette installs on its own:
 
-The design page has the repository too: open it with `mdeck design my-talk.md`, and under **From the theme repository** press **Show what others made**. Each pack shows a picture and an **Install** button.
+```sh
+mdeck palettes install solarized
+```
+
+They are installed for every deck on this computer, in a folder in your home folder (`~/.mdeck/extensions`). Then choose one at the top of a slide file (`theme: duet`, `palette: solarized`) or in the editor's **Deck** tab.
+
+The design page has the same: open it with `mdeck design`, choose **Show what you can install**, and press **Install** beside a theme or palette.
 
-## For every deck
+## Beside one deck
 
-With `--global`, a pack is installed once for all your decks, in a folder in your home folder (`~/.mdeck/extensions`):
+Give a slide file (or the folder it is in) to put it into the `extensions` folder next to it instead:
 
 ```sh
-mdeck themes install solarized --global
+mdeck themes install duet my-talk.md
 ```
 
-A slide file that uses it works only on your computer. `mdeck check` reminds you, and `mdeck themes install solarized my-talk.md` puts a copy beside the slides. When a deck has its own copy, that one is used.
+The slide folder then carries the theme and its palette, so it works on a computer where they are not installed, for example when you send the folder to a colleague.
 
 ## Update and remove
 
 ```sh
-mdeck themes list my-talk.md       # what is installed, here and for every deck
-mdeck themes update my-talk.md     # newer versions of everything installed here
-mdeck themes remove solarized my-talk.md
+mdeck themes list                  # what comes with mdeck, and what is installed
+mdeck themes update                # newer versions of the installed themes
+mdeck palettes update
+mdeck themes remove duet
+mdeck palettes remove cobalt
 ```
 
-Add `--global` to work on the packs for every deck. If you changed an installed file by hand, `update` and `remove` stop and tell you which one, so your change is not lost; add `--force` to go ahead anyway.
+Add a slide file, or `--local`, to work beside that deck. If you changed an installed file by hand, `update` and `remove` stop and tell you which one, so your change is not lost; add `--force` to go ahead anyway.
 
-## What a pack may contain
+A palette that an installed theme uses by default stays until that theme is removed. A palette made for one theme only (like FHNW's `brand`) comes and goes with that theme.
 
-Packs hold only theme and palette settings (`extension.toml`) and theme stylesheets (`styles.css`). They never contain code that runs in your slides. Fonts may come only from Google Fonts or Bunny Fonts, and stylesheets may not load anything from the web. mdeck checks this again when it installs a pack, and refuses a pack that does not match the checksum the repository lists for it.
+The themes and palettes that come with mdeck can be removed too: `mdeck themes remove aurora` hides it from every deck and from the lists, and `mdeck themes install aurora` brings it back, without the internet. The last theme always stays. A deck without a `theme:` setting uses `neue`; if you removed it, `mdeck check` tells you.
+
+## What may be in one
+
+A theme holds only its settings (`extension.toml`) and its stylesheet (`styles.css`); a palette only its settings. They never contain code that runs in your slides. Fonts may come only from Google Fonts or Bunny Fonts, and stylesheets may not load anything from the web. mdeck checks this again when it installs one, and refuses one that does not match the checksum the repository lists for it.
 
 ## Share your own
 
 1. Make the theme or palette as described in [Create a theme or palette](theme-authoring.html), and fine-tune it with `mdeck design`.
-2. Fork the theme repository and add a folder `packs/<your-pack>/` with a `pack.toml` and one folder per theme or palette:
+2. Fork the theme repository and add it as a folder of its own, `themes/<id>/` or `palettes/<id>/`:
 
 ```text
-packs/
+themes/
   harbour/
-    pack.toml
-    harbour/             a theme
-      extension.toml
-      styles.css
-    harbour-night/       its palette
-      extension.toml
+    extension.toml
+    styles.css
+palettes/
+  harbour-night/
+    extension.toml
 ```
 
+   with a few more settings at the top of `extension.toml`:
+
 ```toml
-schema = 1
-id = "harbour"
-title = "Harbour"
-description = "Navy and brass, with a serif for headings."
 version = "1.0.0"
 author = "Your Name"
 license = "MIT"
-mdeck = ">=2.3.0"
+mdeck = ">=3.1.0"
 ```
 
-3. Check it the way the repository will: `mdeck themes build packs -o site --check` shows every theme and palette in the pack on every kind of slide, light and dark, and fails on text that does not fit or is hard to read.
-4. Open a pull request. Once it is merged, `mdeck themes search` lists it. For a new version, raise `version` in `pack.toml`.
+   A theme names its default palette (`palette = "harbour-night"`); it must be in the repository or come with mdeck, and is installed along with the theme.
+
+3. Check it the way the repository will: `mdeck themes build . -o site --check` shows every theme and palette on every kind of slide, light and dark, and fails on text that does not fit or is hard to read.
+4. Open a pull request. Once it is merged, `mdeck themes search` or `mdeck palettes search` lists it. For a new version, raise `version`.

package/docs/site/examples/first-talk.md

@@ -1,5 +1,5 @@
 ---
-theme: editorial
+theme: academic
 show:
   organization: none
   author: none

package/docs/site/pages.js

@@ -7,7 +7,7 @@ export const pages = [
   { slug: 'layouts', title: 'Choose a slide layout', group: 'Make your presentation', file: 'layouts.md', description: 'Choose a title slide, a big statement, a picture, or two columns.', preview: 'first-talk' },
   { slug: 'pictures-and-video', title: 'Add pictures and video', group: 'Make your presentation', file: 'media.md', description: 'Put an image or a video into your talk and keep its files together.' },
   { slug: 'appearance', title: 'Change the look', group: 'Make your presentation', file: 'appearance.md', description: 'Choose fonts and colors with themes and palettes.' },
-  { slug: 'theme-repository', title: 'Install or share a theme', group: 'Make your presentation', file: 'theme-repository.md', description: 'Themes and palettes other people made, installed with one command, and how to share your own.' },
+  { slug: 'theme-repository', title: 'Install, remove or share a theme', group: 'Make your presentation', file: 'theme-repository.md', description: 'Packs of themes and palettes: those that come with mdeck, more from the theme repository, and how to share your own.' },
   { slug: 'notes-and-presenting', title: 'Add notes and present', group: 'Present and share', file: 'presenting.md', description: 'See your notes, reveal points one at a time, and open the audience screen.' },
   { slug: 'audience', title: 'Ask your audience', group: 'Present and share', file: 'audience.md', description: 'Polls that people answer on their phones, with live results on the slide.' },
   { slug: 'drawing', title: 'Draw on your slides', group: 'Present and share', file: 'drawing.md', description: 'Mark up slides with a pen or an iPad, live or ahead of time, and keep the drawings with the talk.' },

package/examples/custom-layouts/slides.md

@@ -1,5 +1,5 @@
 ---
-theme: terminal
+theme: neue
 meta:
   title: Deck-local layouts
 ---

package/examples/poll/slides.md

@@ -1,5 +1,5 @@
 ---
-theme: duet
+theme: neue
 meta:
   title: "Ask the room"
   author: "Tilman Schieber"

package/examples/python/slides.md

@@ -1,11 +1,11 @@
 ---
-theme: sketch
+theme: academic
 meta:
   title: "Introduction to Python"
   author: "Tilman Schieber"
   organization: "FHNW"
   date: "2026-05-19"
-palette: graphite
+palette: paper
 ---
 
 ---

package/examples/showcase/slides.md

@@ -380,8 +380,8 @@ layout: split
 :::slot left
 ```markdown
 ---
-theme: editorial
-palette: terra
+theme: aurora
+palette: lagoon
 ---
 ```
 :::
@@ -392,7 +392,7 @@ To try them without changing the file, open the **reader view** and choose **Loo
 :::
 
 :::notes
-mdeck has six themes and ten palettes, each light or dark. `mdeck list` shows them all, including any kept in an `extensions` folder beside the deck.
+mdeck has four built-in themes and five palettes, each light or dark. `mdeck list` shows them all, including any kept in an `extensions` folder beside the deck. `mdeck themes search` finds more in the theme repository.
 :::
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeck",
-  "version": "2.3.0",
+  "version": "3.1.0",
   "type": "module",
   "description": "Write slides as a plain text file, present them in the browser, share them as one HTML file or PDF.",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test",
+    "test": "node --test --import ./tests/isolate-home.js",
     "test:browser": "node tools/browser-check.mjs",
     "test:server": "node tools/server-check.mjs",
     "test:docs": "node tools/docs-check.mjs",

package/skills/write-slides/SKILL.md

@@ -34,7 +34,7 @@ If `mdeck` is not installed, rely on the quick reference below.
 ```markdown
 ---
 theme: neue            # theme id from `mdeck list themes`
-palette: terra          # optional: lagoon, swiss, cobalt, nordic, graphite, terra, forest, ember, neon, phosphor, pastel
+palette: nordic         # optional: swiss, nordic, neon, lagoon, paper, or one installed from the theme repository (`mdeck themes search`)
 appearance: light       # optional: light or dark
 meta:
   title: "Talk title"
@@ -135,7 +135,7 @@ Fix anything it reports. When you worked from source material, list what you lef
 
 ## 5. A new look: themes and palettes
 
-When the user wants a look the built-in themes and palettes do not give (their institute's colours, a font, the style of a poster or picture), first run `mdeck themes search` (with a word or two): someone may have shared it, and `mdeck themes install <pack> <deck>.md` puts it beside the deck. Otherwise make it as an extension in `extensions/` beside the deck, never as styling on single slides. Read `extensions.md` from the reference folder first; it lists every setting.
+When the user wants a look the built-in themes and palettes do not give (their institute's colours, a font, the style of a poster or picture), first run `mdeck themes search` or `mdeck palettes search` (with a word or two): someone may have shared it, and `mdeck themes install <theme> <deck>.md` (with its palette) or `mdeck palettes install <palette> <deck>.md` puts it beside the deck, so the slide folder carries it. Otherwise make it as an extension in `extensions/` beside the deck, never as styling on single slides. Read `extensions.md` from the reference folder first; it lists every setting.
 
 - **Colours only: a palette.** `extensions/<id>/extension.toml` with `kind = "palette"`, and every colour role (`--bg`, `--surface`, `--ink`, `--ink-soft`, `--muted`, `--rule`, `--accent`, `--accent-2`, `--on-accent`) in both `[light]` and `[dark]`. Text colours must stay readable on `--bg` and `--surface` in both variants, because themes use the other variant for inverted slides.
 - **Fonts, sizes, spacing or arrangement: a theme.** Copy the folder of the closest built-in theme (`assets/extensions/themes/<id>/` in the mdeck repository or in `$(npm root -g)/mdeck/`) to `extensions/<new-id>/`, change `id` and `title`, then its tokens and `styles.css`. A theme takes no colours of its own: it names its default `palette`, and the colours come from palettes.