docs: document slide.ng 2.0

src/content/built-in/cli.md

@@ -13,48 +13,76 @@ The entry file is `slides.md` unless you name another one. A first argument that
 
 `slide-ng --version` prints the version, `slide-ng --help` lists the commands, and `slide-ng <command> --help` lists that command's flags.
 
+A mistyped command or flag gets the nearest real one: `Unknown command "biuld". Did you mean "build"?`, also for `--verison`, `-P` (for `-p`), `theme ejcet` and `skills instal`. A flag of another command names that command (`build --with-clicks` is a flag of `export`), and `present` says to open `/presenter` of `dev` or of a build.
+
 ## dev
 
 Starts the dev server. This is the default command.
 
 | Flag | Meaning |
 | --- | --- |
-| `--port`, `-p` | Port. Default 4230. |
+| `--port`, `-p` | Port. Default 4230, or the next free one when 4230 is taken. A port given here that is taken stops the server, with a free one to try. |
 | `--open`, `-o` | Open the deck in a browser. |
 | `--remote[=password]` | Listen on every address so other devices can open the deck and follow the presenter. Always with a password: the one given, `SLIDE_NG_PASSWORD`, a prompt on a terminal, or a random one that is printed. See [Remote access](../features/remote-access.md). |
 | `--bind <address>` | The address to listen on with `--remote`. Default `0.0.0.0`. |
 | `--log error\|warn\|info\|silent` | How much of the child programs' output to show. Default `info`. `error` and `silent` hide it. |
 | `--force`, `-f` | Clear the build cache. |
 | `--theme`, `-t` | A theme name or path, instead of the headmatter's. |
+| `--lang <tag>` | Use this language (`tr`, `pt-BR`) instead of the headmatter's `lang`: the interface, the locale of dates and numbers, and `<html lang>`. See [Interface language](../features/interface-language.md). |
 
 `--tunnel` and `--base` are refused with a message. The dev server always runs at `/`.
 
+In a terminal the dev server reads keys, as Slidev's does, and prints a line that lists them:
+
+| Key | What it does |
+| --- | --- |
+| `r` | Restart the generator, the companion server and the Angular dev server. A running presenter timer is kept, and `--open` opens no new tab. |
+| `o` | Open `http://localhost:<port>/` in the default browser. |
+| `e` | Open the entry file in `$VISUAL`, `$EDITOR` (flags allowed, such as `code -w`) or else `code`. Under `npm run` and `npx`, npm's own `EDITOR=vi` counts as unset, so `code` is used when it is installed. |
+| `q` | Quit. Ctrl+C works too. |
+| `c` | With `--remote`, print a QR code of the private address for each network address. Without it, say how to start with it. |
+
+- One deck runs one dev server. A second `slide-ng dev` on the same deck stops before it changes anything, whatever its `--port`, and names the running one. When the default port 4230 is taken by something else, the server takes the next free one and says so (`port 4230 is in use, so the dev server uses 4231`). A `--port` that is taken stops it, with a free port to try. Run two decks side by side from their own folders: the second one moves to the next port by itself.
+- During the first build the port shows a "Building the slides" page, so the port is taken from the start. When that build fails, the page shows the error until the build works, and an open tab then loads the slides by itself.
+- The dev server keeps watching after an editor saves by renaming a new file over the old one (vim, JetBrains, `git checkout`).
+- It also serves MCP over HTTP at `/__mcp`, see [MCP server](../features/mcp.md#over-http-from-the-dev-server).
+
 ## build
 
 Makes a static site. See [Hosting](../guide/hosting.md).
 
+```sh
+slide-ng build a.md b.md --base /talks/   # dist/a/ at /talks/a/, dist/b/ at /talks/b/
+```
+
+With several entries each deck is built in turn into `<out>/<name>/` and served under `<base><name>/`, where `<name>` is the file name without `.md`, as in Slidev. Two entries with the same file name, or a missing one, are refused before the first deck is built. `--out` then belongs to the build as a whole: anything else an earlier build left there is removed.
+
 | Flag | Meaning |
 | --- | --- |
 | `--out`, `-o` | Output folder. Default `dist`. |
 | `--base /talk/` | The path the site is served under. `/talk`, `talk/` and `/talk/` all mean `/talk/`. |
 | `--offline` | A folder that opens from disk. Cannot be combined with `--base`. See [Presenting offline](../guide/offline.md). |
 | `--download` | Also make the PDF and add the download button. Fails when the PDF cannot be made, where `download: true` alone only warns. |
 | `--without-notes` | Leave the speaker notes out. |
+| `--router-mode` | `history`, `hash` or `memory`. Replaces the headmatter's `routerMode` for this build, and the build records it for `export --dist`. With `--offline` only `hash`. See [Slide addresses](../features/routing.md). |
 | `--executable-path` | The Chromium to use for the PDF, the install icons and the Open Graph picture. |
 | `--no-sandbox` | Run that Chromium without its sandbox. Needed as root or in a container. Use it for trusted decks only. |
 | `--allow-local` | Let the page Chromium renders reach loopback and private addresses. They are blocked otherwise. |
 | `--timeout` | Timeout in milliseconds for each page Chromium renders. |
 | `--theme`, `-t` | A theme name or path. |
+| `--lang <tag>` | Use this language instead of the headmatter's `lang`, for one deck in several languages: `slide-ng build slides.tr.md --out dist/tr`. |
 
 ## export
 
 Makes a PDF, PNG, PPTX or Markdown file. See [Export](../guide/export.md).
 
+With several entries (`slide-ng export a.md b.md`) each deck is built and exported in turn, to its own file. `--output`, `--dist` and `--url` name one place, so they are refused then, and so are two decks that would get the same file name. To export one deck of a build of several, name its folder: `slide-ng export a.md --dist dist/a`.
+
 | Flag | Meaning |
 | --- | --- |
 | `--format` | `pdf` (default), `png`, `pptx` or `md`. |
 | `--output`, `-o` | Output name or path. |
-| `--range 1,4-5` | Which slides. |
+| `--range 1,4-5` | Which slides. Text that is not a range, such as `2-x`, is refused. |
 | `--with-clicks`, `-c` | One page per click step. On by default for `pptx`. |
 | `--dark` | Dark mode. |
 | `--timeout` | Milliseconds, 1000 to 600000. Default 30000. |
@@ -63,28 +91,29 @@ Makes a PDF, PNG, PPTX or Markdown file. See [Export](../guide/export.md).
 | `--executable-path` | The Chromium to use. Or set `CHROME_PATH`. |
 | `--no-sandbox` | Run Chromium without its sandbox, as root or in a container. Or set `SLIDE_NG_NO_SANDBOX=1`. |
 | `--allow-local` | Let the exported page reach loopback and private addresses. |
-| `--per-slide` | Make each slide separately and join them. |
+| `--per-slide` | Make each slide separately and join them. Links between slides and the tags for screen readers are lost, and the command says so. Use it only for a deck too big to print in one go. |
 | `--scale` | Device scale factor, 0.25 to 8. Default 2. |
 | `--omit-background` | A transparent background. |
 | `--with-toc` | Put an outline made from slide titles into the PDF. |
-| `--dist <folder>` | Export an existing build instead of building first. |
+| `--dist <folder>` | Export an existing build instead of building first, with the router mode it was built with. |
 | `--url <address>` | Export a running server, for example the dev server. |
-| `--base` | The base path the deck is served under, for `--dist`. |
+| `--base` | The base path the build at `--dist` was made with. Read from its `index.html` when left out. |
 | `--theme`, `-t` | A theme name or path. |
+| `--lang <tag>` | Use this language instead of the headmatter's `lang`. Refused with `--dist` and `--url`, whose language was fixed when they were built. |
 
-`export` takes one entry file per run. A `--range` that picks no slide fails before the deck is built.
+A `--range` that picks no slide fails before the deck is built.
 
 ## export-notes
 
-Writes a PDF of the speaker notes. Takes `--output`, `--range` and the Chromium flags of `export`.
+Writes a PDF of the speaker notes. Takes `--output`, `--range` and the Chromium flags of `export`, and several entries as `export` does. The date on it is written in the deck's language.
 
 ## format
 
 ```sh
 slide-ng format [slides.md ...]
 ```
 
-Tidies the files given, `slides.md` by default. No flags. See [Formatting](../features/format.md).
+Tidies the files given, `slides.md` by default. No flags. Frontmatter that is not valid YAML stops it with the file, line and slide and what is wrong, and the file is left as it is. See [Formatting](../features/format.md).
 
 ## theme eject
 
@@ -116,14 +145,15 @@ Copies the agent skill into `<dir>/slide-ng`. `--dir` defaults to `.agents/skill
 slide-ng create <folder> [--force]
 ```
 
-Makes a new deck folder. `--force`, `-f` adds the files that are missing to a folder that already has files. See [Your first deck](../getting-started/first-deck.md).
+Makes a new deck folder: `slides.md`, `package.json` with the scripts `dev`, `build`, `export` and `format`, a README and `.gitignore`. It refuses a folder with files. `--force`, `-f` adds only the files that are missing, fills in the name only in the files it adds, and keeps an existing `.gitignore`. The `.gitignore` leaves out what `export` and `export-notes` write by default. See [Your first deck](../getting-started/first-deck.md).
 
 ## Environment
 
 | Variable | Meaning |
 | --- | --- |
 | `CHROME_PATH` | The Chromium that export, `--download`, `pwa` icons and `ogImage: auto` use. |
 | `SLIDE_NG_THEME` | A theme name or path that overrides the headmatter. `--theme` sets it. |
+| `SLIDE_NG_LANG` | The same as `--lang`. |
 | `SLIDE_NG_NO_SANDBOX` | `1` is the same as `--no-sandbox`. |
 | `SLIDE_NG_PASSWORD` | The password for `dev --remote`. It keeps the password out of the shell history. |
 | `SLIDES_FILE` | The entry file, when no argument names one. |

src/content/built-in/components.md

@@ -14,16 +14,18 @@ These tags work in every slide. The generator imports a component only into the
 | `<slide-ng-toc />` | Table of contents from slide titles and levels. Options: `columns`, `listClass`, `listStyle`, `start`, `minDepth`, `maxDepth`, `mode`. See [Table of contents](../features/table-of-contents.md). |
 | `<slide-ng-current-no />` | The number of the slide it is on. |
 | `<slide-ng-total />` | The number of slides. |
+| `<slide-ng-progress-bar />` | A bar that shows how far through the deck the slide is. Options: `position` (`top`, `bottom`, `inline`), `height`, `color`, `track`, `clicks`, `minutes`. See [Progress bar](../features/progress-bar.md). |
+| `<slide-ng-title-renderer />` | The title of the slide it is on, as HTML: its inline markdown and `$math$` are drawn. `no="3"` shows the title of slide 3. Raw HTML in a title is shown as text. Slidev's `TitleRenderer`. |
 | `<slide-ng-link to="3">text</slide-ng-link>` | A link to slide 3, or to a `routeAlias`. It has the prefix because `link` is a built-in HTML tag. The link has the slide's real address, so Ctrl or Cmd + click opens it in a new tab. `title="Details"` is the text when the tag has none. |
 | `<slide-ng-light-or-dark>` | Shows `<div dark>...</div>` in dark mode and `<div light>...</div>` in light mode. |
-| `<slide-ng-render-when context="slide">` | Content only where the slide is drawn: `slide`, `presenter`, `print`, `overview`, or `main` (slide or presenter). `[context]="['slide','overview']"` takes several. Content marked `<div fallback>` shows everywhere else. |
+| `<slide-ng-render-when context="slide">` | Content only where the slide is drawn: `slide`, `presenter`, `print`, `overview`, or `main` (slide or presenter). `visible` shows it while the element is on the screen. `[context]="['slide','overview']"` takes several, and in a list `visible` must hold too. Content marked `<div fallback>` shows everywhere else. In print and export every slide counts as visible. |
 
 ## Clicks
 
 | Tag | What it does |
 | --- | --- |
-| `<slide-ng-clicks>` | Gives each child a click, as Slidev's `v-clicks`: each item of a single list, each body row of a single table, otherwise each child element (paragraphs, pictures, several lists). Options: `depth`, `every`, `at`, `hide`. |
-| `<slide-ng-switch>` | One child per click: `<slide-ng-switch><div at="1">a</div><div at="2">b</div><div at="3-5">c</div></slide-ng-switch>`. A number lasts until the next one starts. `3-5` is clicks 3 and 4: the end is not included. |
+| `<slide-ng-clicks>` | Gives each child a click, as Slidev's `v-clicks`: each item of a single list, each body row of a single table, otherwise each child element (paragraphs, pictures, several lists). Options: `depth`, `every`, `at`, `hide`, `animation`. |
+| `<slide-ng-switch>` | One child per click: `<slide-ng-switch><div at="1">a</div><div at="2">b</div><div at="3-5">c</div></slide-ng-switch>`. A number lasts until the next one starts. `3-5` is clicks 3 and 4: the end is not included. `unmount` takes the children that are not shown out of the page; their components stay alive. `transition="fade"` animates the change, also with `slide-left`, `slide-up`, `fade-out`, a `forward \| backward` pair or a [transition of your own](../guide/animations.md#your-own-transition); a bare `transition` is a fade. |
 | `<slide-ng-click-gap size="2" />` | Leaves two clicks empty. |
 
 `slide-ng-click` and `slide-ng-after` are directives, see [Directives](./directives.md).
@@ -42,8 +44,8 @@ These tags work in every slide. The generator imports a component only into the
 
 | Tag | What it does |
 | --- | --- |
-| `<slide-ng-youtube id="luoMHjh-XcQ" width="560" height="315" />` | An embedded YouTube video. `id` is the video id. There are no start time or playlist options. |
-| `<slide-ng-video autoplay="true" autoreset="click" controls poster="...">` | A video that plays when its slide, or its `slide-ng-click`, comes. `autoplay="once"` plays once. `timestamp` starts at a second. Put `<source>` tags inside. |
+| `<slide-ng-youtube id="luoMHjh-XcQ?start=60" width="560" height="315" />` | An embedded YouTube video. `id` is the video id, optionally followed by YouTube's embed options, as in Slidev: `?start=60&end=90`, `list`, `loop`, `autoplay`, `mute` and the other documented ones. Other options are dropped. `start` (seconds) and `list` (a playlist id) can also be attributes, and they win over the same option in `id`. A start time, `start` or the `t` of a shared link, may be written YouTube's way, `1m30s` or `1h2m3s`; anything else is dropped with a warning. |
+| `<slide-ng-video autoplay="true" autoreset="click" controls poster="...">` | A video that plays when its slide, or its `slide-ng-click`, comes. `autoplay="once"` plays once. `timestamp` starts at a second. Put `<source>` tags inside. A class or size on it, such as `class="h-60"`, sizes the video, which keeps its shape. Where the video does not play (print, export, overview), `printPoster="/still.png"` replaces `poster`, and `printTimestamp="12"` (seconds, or `last`) picks the frame to show. |
 | `<slide-ng-tweet id="20" scale="0.8" conversation="none" cards="hidden" />` | An embedded tweet. Loads Twitter's script, so it needs the network. |
 | `<slide-ng-blue-sky uri="at://did:.../app.bsky.feed.post/..." scale="0.8" />` | An embedded Bluesky post, needs the network. `uri` can also be the post's web address. |
 
@@ -63,4 +65,4 @@ These tags work in every slide. The generator imports a component only into the
 
 ## Not there
 
-Slidev's `PoweredBySlidev` badge and `TitleRenderer` are not available. Slide titles are plain text, except that `$math$` in a title is drawn in `<slide-ng-toc>`. Your own components work like these, see [Layouts and components](../customize/layouts-components.md).
+Slidev's `PoweredBySlidev` badge is not available. Your own components work like these, see [Layouts and components](../customize/layouts-components.md).

src/content/built-in/directives.md

@@ -9,16 +9,20 @@ Directives are attributes you put on an HTML element in a slide.
 
 | Directive | What it does | Page |
 | --- | --- | --- |
-| `slide-ng-click` | Shows the element at a click. Takes nothing, a number (`"3"`), a relative step (`"+2"`) or, as a binding, a range `[slide-ng-click]="[2, 4]"`. | [Clicks](../guide/animations.md) |
+| `slide-ng-click` | Shows the element at a click. Takes nothing, a number (`"3"`), a relative step (`"+2"`) or a range, `[slide-ng-click]="[2, 4]"` or `slide-ng-click="[2, 4]"`. `slide-ng-click.hide` hides the element at its click instead. | [Clicks](../guide/animations.md) |
 | `slide-ng-after` | Shows the element at the same click as the one before it, a relative `+0`. | [Clicks](../guide/animations.md) |
-| `slide-ng-click-hide` | With `slide-ng-click`, hides the element at the click instead of showing it. | [Clicks](../guide/animations.md) |
+| `slide-ng-click-hide` | Hides the element at a click: `slide-ng-click-hide="3"` at click 3. As a bare flag next to `slide-ng-click`, it hides at that click instead of showing. | [Clicks](../guide/animations.md) |
 | `slide-ng-mark` | Draws a hand-made mark at a click. Modifiers pick type and colour. | [Marks](../features/marks.md) |
 | `slide-ng-motion` | Moves an element between named states. | [Motion](../features/motion.md) |
 | `slide-ng-drag` | Makes an element movable and resizable, and saves the position. Takes `[x, y, width, height]`, a name from `dragPos`, or nothing. | [Draggable elements](../features/draggable.md) |
 
 ## Two forms of the same value
 
-Angular reads `slide-ng-click="3"` as plain text, and slide.ng turns it into the number 3. For a value that is computed, or an array, use a binding: `[slide-ng-click]="[2, 4]"`.
+Angular reads `slide-ng-click="3"` as plain text, and slide.ng turns it into the number 3. For a value that is computed, use a binding: `[slide-ng-click]="[2, 4]"`. A range written as text, `slide-ng-click="[2, 4]"`, is bound for you.
+
+## Modifiers
+
+Click animation presets go after the name, as in Slidev: `slide-ng-click.fade.right`, `slide-ng-after.up`, `slide-ng-click-hide.none`. See [Click animations](../features/click-animations.md). `.hide` on `slide-ng-click` or `slide-ng-after` hides the element at its click. A modifier one or two letters away from a known one gets a warning.
 
 ## Relative and absolute clicks
 
@@ -30,4 +34,4 @@ A bare `slide-ng-click`, `+n`, `slide-ng-after` and a bare `slide-ng-mark` count
 
 ## Not available
 
-Vue's own directives (`v-if`, `v-for`, `v-model`, `v-bind`) are not there. Use Angular's control flow, see [Angular in markdown](../guide/angular-templates.md). Slidev's slide hooks (`onSlideEnter`, `onSlideLeave`) are not supported either.
+Vue's own directives (`v-if`, `v-for`, `v-model`, `v-bind`) are not there. Use Angular's control flow, see [Angular in markdown](../guide/angular-templates.md). Slidev's slide hooks are functions for components, see [Layouts and components](../customize/layouts-components.md#slide-hooks).