docs: document navPosition and one deck in several languages (2.1)

src/content/built-in/cli.md

@@ -28,7 +28,7 @@ Starts the dev server. This is the default command.
 | `--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). |
+| `--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>`. With `languages`, the language the page starts in. See [Interface language](../features/interface-language.md). |
 
 `--tunnel` and `--base` are refused with a message. The dev server always runs at `/`.
 
@@ -70,7 +70,7 @@ With several entries each deck is built in turn into `<out>/<name>/` and served
 | `--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`. |
+| `--lang <tag>` | Use this language instead of the headmatter's `lang`, as in `slide-ng build slides.tr.md --out dist/tr`. With `languages`, the language the page starts in. See [One deck in several languages](../features/interface-language.md#one-deck-in-several-languages). |
 
 ## export
 
@@ -99,7 +99,7 @@ With several entries (`slide-ng export a.md b.md`) each deck is built and export
 | `--url <address>` | Export a running server, for example the dev server. |
 | `--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. |
+| `--lang <tag>` | Use this language instead of the headmatter's `lang`. With `languages`, export the slides of that language: `slide-ng export --lang tr`. Refused with `--dist` and `--url`, whose language was fixed when they were built. |
 
 A `--range` that picks no slide fails before the deck is built.
 

src/content/built-in/headmatter.md

@@ -44,6 +44,7 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck.
 | `zoom` | Scale every slide. |
 | `routerMode` | `history` (default), `hash` or `memory`. See [Slide addresses](../features/routing.md). |
 | `clickAnimation` | The click animation preset of every slide. |
+| `navPosition` | Where the navigation bar sits on the slide page: `bottom-left` (default), `bottom-center`, `bottom-right`, `top-left`, `top-center` or `top-right`. Left and right follow the writing direction, so a right-to-left deck mirrors them. At the top, the bar's menus open below it. The presenter page keeps its bar. Another value is warned about and keeps the bottom left. Not in Slidev. |
 | `progressBar` | A progress bar on every slide: `true`, `top`, `bottom` or an object. See [Progress bar](../features/progress-bar.md). |
 | `preloadImages` | `true` (default), `{ ahead: n }` or `false`. See [Loading pictures ahead](../features/preload-images.md). |
 | `unocss` | `{ attributify: false }` turns attributify off. See [UnoCSS](../features/unocss.md). |
@@ -84,6 +85,7 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck.
 | --- | --- |
 | `titleTemplate`, `author`, `keywords`, `favicon`, `htmlAttrs`, `seoMeta` | The page's `<head>`. See [Page head and SEO](../features/seo-meta.md). |
 | `lang`, `uiLang` | `lang` is `<html lang>`, the interface language and the locale of the `date`, `number` and `currency` pipes. `ar`, `he`, `fa` and `ur` mirror the page. `uiLang` changes the interface language only. See [Interface language](../features/interface-language.md). |
+| `languages` | One file per language, such as `{ en: slides.md, tr: slides.tr.md }`, in the entry file. The bar gets a language menu. See [One deck in several languages](../features/interface-language.md#one-deck-in-several-languages). |
 | `download` | A PDF button: `true`, a file name or an address. With `true`, `slide-ng build` makes the PDF. Without a working Chromium it warns and the button stays disabled. |
 | `exportFilename` | The name of exported files, without the extension. |
 | `export` | Defaults for `slide-ng export`. See [Export](../guide/export.md). |

src/content/built-in/shortcuts.md

@@ -22,7 +22,7 @@ Shortcuts are off while you type in a text field or an editor, and while the dra
 
 ## Mouse
 
-The bar at the bottom left has buttons for fullscreen, previous, next, overview, dark mode, drawing, presenter mode, info, sync mode, settings and a counter. It shows when the mouse is there. On the presenter page it also has the layout button and the [click preview](../guide/presenter-mode.md#click-preview). A `layers/custom-nav-controls.ts` adds buttons of your own at its end, see [Global layers](../features/global-layers.md). The fullscreen button is left out where the page may not go fullscreen: in an iframe without `allow="fullscreen"`, and on an iPhone. `f` does nothing there.
+The bar at the bottom left has buttons for fullscreen, previous, next, overview, dark mode, drawing, presenter mode, info, sync mode, settings and a counter. A deck with `languages` also has a language button before the settings, see [One deck in several languages](../features/interface-language.md#one-deck-in-several-languages). The bar shows when the mouse is there. `navPosition` in the headmatter puts it in another corner, or in the middle of the top or bottom edge, see [Headmatter and frontmatter](./headmatter.md#the-deck-and-its-look). On the presenter page the bar stays where it is and also has the layout button and the [click preview](../guide/presenter-mode.md#click-preview). A `layers/custom-nav-controls.ts` adds buttons of your own at its end, see [Global layers](../features/global-layers.md). The fullscreen button is left out where the page may not go fullscreen: in an iframe without `allow="fullscreen"`, and on an iPhone. `f` does nothing there.
 
 <ngmd-image src="/images/ui/nav-bar-light.png" alt="The navigation bar at the bottom left of a slide" caption="The navigation bar" width="480"></ngmd-image>
 

src/content/features/interface-language.md

@@ -1,11 +1,11 @@
 ---
 title: Interface language
-description: Show the bar, the menus and the presenter in the deck's language, and translate them with a JSON file.
+description: Show the bar, the menus and the presenter in the deck's language, translate them with a JSON file, and switch one deck between languages.
 ---
 
 # Interface language
 
-slide.ng's own interface is in English: the bar and its tooltips, the settings and sync menus, the overview, the go-to box, the right-click menu, the presenter and its click preview, the `/overview` and notes pages, the info dialog, the drawing toolbar and the password prompt of `dev --remote`. The headmatter's `lang` picks another language. Turkish is built in.
+slide.ng's own interface is in English: the bar and its tooltips, the settings, sync and language menus, the overview, the go-to box, the right-click menu, the presenter and its click preview, the `/overview` and notes pages, the info dialog, the drawing toolbar and the password prompt of `dev --remote`. The headmatter's `lang` picks another language. Turkish is built in.
 
 ```md
 ---
@@ -18,6 +18,7 @@ uiLang: en # optional: the interface in another language than the slides
 | --- | --- |
 | `lang` | The language of the deck: `<html lang>`, the interface language and the locale of the `date`, `number`, `currency` and `percent` pipes. |
 | `uiLang` | The interface language only. It wins over `lang`. |
+| `languages` | One file per language, such as `{ en: slides.md, tr: slides.tr.md }`, and a language menu in the bar. See [One deck in several languages](#one-deck-in-several-languages). |
 
 A tag is written the usual way: `pt_br` is read as `pt-BR`. Without either key the interface is English.
 
@@ -44,7 +45,7 @@ The keys and their English text are listed in [UI-STRINGS.md](https://github.com
 {{ price | currency: 'EUR' }} · {{ day | date }} · {{ n | number }}
 ```
 
-Only that locale's data goes into the build. `pt-BR` uses Angular's `pt-BR` data, or else `pt`. A language Angular has no data for is written the English way, and the generator says so. `uiLang` does not change the locale. The date on the notes PDF follows `lang` too.
+Only that locale's data goes into the build, or each language's with `languages`. `pt-BR` uses Angular's `pt-BR` data, or else `pt`. A language Angular has no data for is written the English way, and the generator says so. `uiLang` does not change the locale. The date on the notes PDF follows `lang` too.
 
 The "go to" box (`g`) compares titles by the rules of the deck's language and without accents, so in a Turkish deck `izmir` finds "İzmir" and `cafe` finds "Café". A slide number may be typed with Arabic-Indic or Persian digits (`٣`, `۵`).
 
@@ -60,7 +61,55 @@ The "go to" box (`g`) compares titles by the rules of the deck's language and wi
 
 ## One deck in several languages
 
-Write one entry file per language, and import the slides that are the same in every language with `src:`:
+Write the slides of each language in a file of its own, and list the files in the headmatter of the entry file:
+
+```md
+---
+title: My talk
+languages:
+  en: slides.md
+  tr: slides.tr.md
+---
+
+# Hello
+```
+
+`slides.tr.md` has the Turkish slides, in the same order:
+
+```md
+---
+title: Konuşmam
+---
+
+# Merhaba
+```
+
+The bar then has a language button, with a translate icon. Its menu lists the languages, each named in its own language, with the current one ticked. Choosing one keeps the address and the slide. It switches the slides, `<html lang>` and `dir`, the page title, the locale of the pipes and the interface text.
+
+- The page loads again for the switch, because Angular fixes the locale when the app starts.
+- The choice is kept in the browser, per deck, like the other settings. The presenter and audience windows of one browser switch together. Another device keeps its own choice.
+- A page starts in the entry file's language until the reader chooses another.
+- It works in `dev`, in a build and in an offline folder.
+
+Each file is read as a deck. Its headmatter goes over the entry file's, so you can translate `title`, `info` and `titleTemplate`, and write the theme, `fonts` and the rest once. The key in `languages` is its `lang`, and its `uiLang` is its own. The theme, addons, `allowOutsideRoot` and the page's `<head>` come from the entry file.
+
+Slides are paired by number, because the number is the address:
+
+- A slide takes the frontmatter of the entry file's slide with the same number, under its own. So `layout`, `routeAlias`, `clicks` and `class` are written once, in the entry file. Its `title` is not taken.
+- The generator warns, with files and lines, when the files have a different number of slides.
+- A slide the translation does not have is shown from the entry file. A slide past the entry file's last is left out.
+- `hide: true` drops a slide from its own file only, so hide it in every file.
+- Drawings belong to a slide number, so the languages share them.
+
+In `dev`, the side editor, the notes editor and `slide-ng-drag` write to the file of the language on screen. Every file listed is watched.
+
+`--lang tr` on `dev` and `build` starts the page in Turkish, and `slide-ng export --lang tr` exports the Turkish slides. A language that is not in `languages` is warned about and ignored. See the [CLI reference](../built-in/cli.md).
+
+A deck without `languages` has no language button and nothing of the switch in its build.
+
+### One build per language
+
+Without `languages`, you can still write one entry file per language, and import the slides that are the same in every language with `src:`:
 
 ```
 slides.md        lang: en
@@ -75,16 +124,16 @@ slide-ng build slides.md --out dist/en
 slide-ng build slides.tr.md --out dist/tr
 ```
 
-`--lang tr` on `dev`, `build` and `export` sets `lang` for one run without changing the file, and replaces `uiLang` too, so the interface follows it. `SLIDE_NG_LANG` does the same. See the [CLI reference](../built-in/cli.md).
+`--lang tr` on `dev`, `build` and `export` then sets `lang` for one run without changing the file, and replaces `uiLang` too, so the interface follows it. `SLIDE_NG_LANG` does the same.
 
 `--lang` is for slides written in that language. It also sets `<html lang>` and the language of the PDF, so `--lang en` on a Turkish deck tells screen readers that the Turkish text is English. To change only the interface, set `uiLang` in the headmatter instead.
 
-The language of a deck is fixed when it is built, so `export --dist` and `export --url` refuse `--lang`. Build each language with `slide-ng build --lang <tag>`, then export that folder.
+The language of a build is fixed when it is built, so `export --dist` and `export --url` refuse `--lang`. Build each language with `slide-ng build --lang <tag>`, then export that folder.
 
 ## Limits
 
 - Turkish is the only built-in translation.
 - Error messages that come from the browser (camera, recording, screen sharing) and the generator's warnings stay English.
 - In a right-to-left deck the keys and the transitions are not mirrored, on purpose, as in Slidev.
-- The language cannot be switched while presenting. Build one deck per language instead.
+- With `languages`, a switch loads the page again, so a running presenter timer, an open dialog and unsaved text in the side editor are lost. Other devices keep their own language.
 - The built-in context menu labels follow the language, so a `setup/context-menu.ts` should pick an entry by its `icon`, not its label.

src/content/guide/export.md

@@ -62,7 +62,7 @@ slide-ng export --dist dist          # export a build you already made
 slide-ng export --url http://localhost:4230/   # export a running server
 ```
 
-`--dist` opens the build with the router mode it was built with. `--lang` cannot change the language of an existing build or a running server, so it is refused with `--dist` and `--url`.
+`--dist` opens the build with the router mode it was built with. `--lang` cannot change the language of an existing build or a running server, so it is refused with `--dist` and `--url`. For a deck with `languages`, `slide-ng export --lang tr` builds the deck and exports its Turkish slides.
 
 Without `--dist` or `--url`, export builds the deck first, in its own working copy, so it does not disturb a dev server that is running. If the page never goes idle, the export says so: try `--wait-until load`.
 

src/content/guide/presenter-mode.md

@@ -96,7 +96,7 @@ Use one presenter page. Two presenter pages do not follow each other: each keeps
 
 ### Sync mode
 
-The sync button in the bar (up and down arrows, before the settings) opens Slidev's sync mode menu:
+The sync button in the bar (up and down arrows, near the settings) opens Slidev's sync mode menu:
 
 | Mode | What the window does |
 | --- | --- |

src/content/migrating/from-slidev.md

@@ -20,7 +20,9 @@ slide.ng reads the same markdown file format as *Slidev, with the same slide spl
 
 - A click preview on the presenter page: the eye button or `u` shows what the later clicks of the current slide show, greyed out, and a click on a part goes to its click. See [Presenter mode](../guide/presenter-mode.md#click-preview).
 - A progress bar on the slides, `progressBar` or `<slide-ng-progress-bar />`. Slidev has one on its presenter page only. See [Progress bar](../features/progress-bar.md).
+- `navPosition` puts the navigation bar in any corner, or in the middle of the top or bottom edge. Slidev's bar is always at the bottom left. See [Headmatter and frontmatter](../built-in/headmatter.md#the-deck-and-its-look).
 - A built-in Turkish interface and `locales/<lang>.json` to translate the interface. See [Interface language](../features/interface-language.md).
+- One deck in several languages, with a language menu in the bar that switches the slides and the interface. See [Interface language](../features/interface-language.md#one-deck-in-several-languages).
 
 ## Syntax differences