diff --git a/src/content/built-in/cli.md b/src/content/built-in/cli.md index 372de73..acf21f0 100644 --- a/src/content/built-in/cli.md +++ b/src/content/built-in/cli.md @@ -26,6 +26,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 ` | Use this language (`tr`, `pt-BR`) instead of the headmatter's `lang`: the interface, the locale of dates and numbers, and ``. See [Interface language](../features/interface-language.md). | `--tunnel` and `--base` are refused with a message. The dev server always runs at `/`. @@ -45,6 +46,7 @@ Makes a static site. See [Hosting](../guide/hosting.md). | `--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 ` | 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 @@ -71,6 +73,7 @@ Makes a PDF, PNG, PPTX or Markdown file. See [Export](../guide/export.md). | `--url
` | Export a running server, for example the dev server. | | `--base` | The base path the deck is served under, for `--dist`. | | `--theme`, `-t` | A theme name or path. | +| `--lang ` | Use this language instead of the headmatter's `lang`. | `export` takes one entry file per run. A `--range` that picks no slide fails before the deck is built. @@ -124,6 +127,7 @@ Makes a new deck folder. `--force`, `-f` adds the files that are missing to a fo | --- | --- | | `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. | diff --git a/src/content/built-in/components.md b/src/content/built-in/components.md index a1c687d..0ea7fd3 100644 --- a/src/content/built-in/components.md +++ b/src/content/built-in/components.md @@ -14,6 +14,7 @@ These tags work in every slide. The generator imports a component only into the | `` | 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). | | `` | The number of the slide it is on. | | `` | The number of slides. | +| `` | 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`. | | `text` | 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. | | `` | Shows `
...
` in dark mode and `
...
` in light mode. | | `` | Content only where the slide is drawn: `slide`, `presenter`, `print`, `overview`, or `main` (slide or presenter). `[context]="['slide','overview']"` takes several. Content marked `
` shows everywhere else. | @@ -42,7 +43,7 @@ These tags work in every slide. The generator imports a component only into the | Tag | What it does | | --- | --- | -| `` | An embedded YouTube video. `id` is the video id. There are no start time or playlist options. | +| `` | 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 video that plays when its slide, or its `slide-ng-click`, comes. `autoplay="once"` plays once. `timestamp` starts at a second. Put `` tags inside. | | `` | An embedded tweet. Loads Twitter's script, so it needs the network. | | `` | An embedded Bluesky post, needs the network. `uri` can also be the post's web address. | @@ -63,4 +64,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 ``. 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). diff --git a/src/content/built-in/headmatter.md b/src/content/built-in/headmatter.md index b0c7199..b6c34a0 100644 --- a/src/content/built-in/headmatter.md +++ b/src/content/built-in/headmatter.md @@ -42,6 +42,7 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck. | `zoom` | Scale every slide. | | `routerMode` | `history` (default) or `hash`. | | `fonts` | Web fonts. See [Fonts](../features/fonts.md). | +| `themeConfig` | Settings for the theme, such as `themeConfig: { primary: '#5d8392' }`. Each text or number key becomes the CSS variable `--slidev-theme-`. See [Themes and addons](../customize/themes.md#theme-settings). | | `customElements` | Web component tags the slides may use, such as `[model-viewer, sl-*]`. A name ending in `*` is a prefix, and `true` allows any tag with a dash. See [Layouts and components](../customize/layouts-components.md#web-components). | ### Code and diagrams @@ -71,7 +72,8 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck. | Key | What it does | | --- | --- | -| `titleTemplate`, `author`, `keywords`, `favicon`, `lang`, `htmlAttrs`, `seoMeta` | The page's ``. See [Page head and SEO](../features/seo-meta.md). | +| `titleTemplate`, `author`, `keywords`, `favicon`, `htmlAttrs`, `seoMeta` | The page's ``. See [Page head and SEO](../features/seo-meta.md). | +| `lang`, `uiLang` | `lang` is ``, 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). | | `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). | @@ -81,4 +83,4 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck. ## Not read -These Slidev keys are accepted in the file but have no effect: `selectable`, `themeConfig`, `preload`, `clickAnimation`, `overviewSnapshots`, `browserExporter`, `notesAutoRuby`, `monacoTypesSource`, and `colorSchema: all`. `mdc: true` and `comark: true` have no effect, and the generator warns that MDC syntax stays text. `highlighter: prism` warns too, because code is always highlighted with Shiki. The `monaco` and `twoslash` switches of Slidev are not read either: a `{monaco}` or `twoslash` code fence is what turns them on. A key a theme brings through `theme.json` is merged under the deck's headmatter, except a fixed `colorSchema`, see [Themes and addons](../customize/themes.md). +These Slidev keys are accepted in the file but have no effect: `selectable`, `preload`, `clickAnimation`, `overviewSnapshots`, `browserExporter`, `notesAutoRuby`, `monacoTypesSource`, and `colorSchema: all`. `mdc: true` and `comark: true` have no effect, and the generator warns that MDC syntax stays text. `highlighter: prism` warns too, because code is always highlighted with Shiki. The `monaco` and `twoslash` switches of Slidev are not read either: a `{monaco}` or `twoslash` code fence is what turns them on. A key a theme brings through `theme.json` is merged under the deck's headmatter, except a fixed `colorSchema`, see [Themes and addons](../customize/themes.md). diff --git a/src/content/customize/directory-structure.md b/src/content/customize/directory-structure.md index 60c0dc9..1f06818 100644 --- a/src/content/customize/directory-structure.md +++ b/src/content/customize/directory-structure.md @@ -16,6 +16,7 @@ my-deck/ styles/index.css CSS added after the app's styles public/ files served from the site root (/logo.png) setup/ setup hooks: shiki.ts, katex.ts, mermaid.ts, shortcuts.ts, ... + locales/ translations of the interface: tr.json, de.json, ... uno.config.mjs UnoCSS settings theme.json inputs and slots of your own layouts snippets/ anything you import with <<< @@ -42,6 +43,7 @@ So a deck can put a `layouts/cover.ts` next to `slides.md` and it beats the them | `styles/index.css` | CSS, added after the app's styles. | | `public/` | Files served from the site root. The later root wins on the same name. | | `setup/*.ts` | [Setup hooks](./setup-hooks.md). | +| `locales/.json` | Translations of the interface, flat `"key": "text"` pairs. Merged key by key, the later root wins. See [Interface language](../features/interface-language.md). | | `uno.config.mjs` | UnoCSS settings, default export. `presets`, `rules`, `safelist` and `variants` are added to the app's. `shortcuts` and `theme` are merged key by key. | | `theme.json` | Name, default headmatter and layout inputs and slots. A deck's own folder can have one too, for its own layouts. See [Writing a theme](./writing-a-theme.md). | diff --git a/src/content/customize/setup-hooks.md b/src/content/customize/setup-hooks.md index 9fd17c9..846637a 100644 --- a/src/content/customize/setup-hooks.md +++ b/src/content/customize/setup-hooks.md @@ -135,7 +135,7 @@ See [Shortcuts](../built-in/shortcuts.md). The roots are chained: each gets the ## Context menu -`setup/context-menu.ts` gets the entries of the right-click menu and returns the list to show. An entry is `{ icon, label, run, disabled? }`, and `icon` is an icon class such as `i-carbon:star`. The roots are chained. +`setup/context-menu.ts` gets the entries of the right-click menu and returns the list to show. An entry is `{ icon, label, run, disabled? }`, and `icon` is an icon class such as `i-carbon:star`. The roots are chained. The built-in labels are in the deck's [interface language](../features/interface-language.md), so pick an entry by its `icon`, not its label. ```ts // setup/context-menu.ts diff --git a/src/content/customize/themes.md b/src/content/customize/themes.md index 83ffe13..6f20483 100644 --- a/src/content/customize/themes.md +++ b/src/content/customize/themes.md @@ -48,6 +48,35 @@ A theme can bring layouts, components, layers, CSS, public files, UnoCSS setting The one exception is `colorSchema`. A theme that sets `light` or `dark` has colours for that mode only, so every deck that uses it keeps that mode, as in Slidev. The toggle is gone, and when the deck's headmatter asks for another mode the generator says that it is not used. Of the official themes, `bricks` is light only and `shibainu` dark only. +## Theme settings + +`themeConfig` holds the values a theme offers to change, as in Slidev. Each key with a text or number value becomes the CSS variable `--slidev-theme-` on ``, with the key as written: `primary` is `--slidev-theme-primary`, `accentDark` is `--slidev-theme-accentDark`. It is there in the page, the presenter, the PDF and offline builds. + +```md +--- +themeConfig: + primary: '#5d8392' +--- +``` + +`primary` recolours the built-in accent: `text-primary`, `bg-primary`, `border-primary`, the progress bar and the controls. Other keys do what the theme makes of them. + +- The theme's `theme.json` can give defaults. The deck's keys win, key by key, and so do an addon's. +- A key must be letters, digits, `-` and `_`. A value that could leave the CSS declaration (`;`, `{`, `}`, `<`, `>`, `\`, a comment, a line break, quotes or brackets that do not close) is skipped with a warning. +- There is one value for both colour modes, as in Slidev. +- A slide reads the whole map as `themeConfig`, for example `{{ themeConfig['primary'] }}`. The brackets are needed because the map has no fixed keys. Lists and objects are kept there, but they are not CSS variables. +- A theme's component reads it with `inject(THEME_CONFIG)` from `slide-ng/lib/theme-config`. See [Writing a theme](./writing-a-theme.md#5-default-settings). + +## Translating the interface + +A theme or an addon can translate slide.ng's own interface (the bar, the menus, the presenter) with a `locales/` folder. `locales/tr.json`, or `pt.json` and `pt-BR.json`, holds flat `"key": "text"` pairs with their `{name}` placeholders kept: + +```json +{ "nav.next": "Sonraki slayta git", "presenter.noNotes": "{no}. slayt için not yok." } +``` + +The deck's `lang` or `uiLang` picks the file. The built-in translations come first, then the theme, the addons and the deck, key by key, so a deck can change one text of its theme. A theme's own components can show the same texts with the `t` pipe: import `T` from `slide-ng/i18n/t`, then write `{{ 'nav.next' | t }}`. See [Interface language](../features/interface-language.md). + ## Eject a theme ```sh @@ -63,7 +92,6 @@ The built-in styles still load before the ejected `styles/index.css`. Your copy - There is no versioning or compatibility check between a theme and the app. - A layout's inputs are not read from the component, because Angular decorators are not parsed. They come from the built-in layout or from `theme.json`. - Class names in a theme are found by UnoCSS in `.ts` files of the roots and in the deck's markdown, not in CSS files. -- `themeConfig` is not read. - `@apply` in a theme's CSS does nothing, because there is no UnoCSS directive transformer. The generator warns. Write the CSS out, or put the classes on the elements. - A theme package whose `files` leaves its folders out installs empty. The generator warns, instead of failing later with "is not a known element". diff --git a/src/content/customize/writing-a-theme.md b/src/content/customize/writing-a-theme.md index 6277242..aa396d1 100644 --- a/src/content/customize/writing-a-theme.md +++ b/src/content/customize/writing-a-theme.md @@ -18,6 +18,7 @@ my-theme/ layers/ optional: global-top.ts, global-bottom.ts, slide-top.ts, slide-bottom.ts setup/ optional: setup hooks public/ optional: pictures and fonts, served from / + locales/ optional: translations of the interface, tr.json, de.json, ... uno.config.mjs optional: UnoCSS shortcuts and rules ``` @@ -86,9 +87,23 @@ Dark mode is the class `dark` on ``: write `html.dark .my-quote { ... }` f - A `colorSchema` of `light` or `dark` says the theme has colours for that mode only: every deck that uses it keeps that mode, and the generator warns when a deck asks for another. Leave it out when the theme styles both. - `layouts.`: `props` are the frontmatter keys that become inputs, `slots` are the names accepted after `::name::`, and `classProp: true` sends the slide's `class` to the input `contentClass` instead of the tag. +Settings a deck may change, such as the accent colour, go in `themeConfig`, as in Slidev. Each one is the CSS variable `--slidev-theme-` on ``, and the deck's `themeConfig: { accent: '#22c55e' }` replaces your default: + +```json +{ "headmatter": { "themeConfig": { "accent": "#f59e0b" } } } +``` + +```css +.my-quote { + border-left: 4px solid var(--slidev-theme-accent); +} +``` + +The variables are written after the roots' style sheets, so they win over a value you set on `:root` or `html.dark`. Use them in rules on the elements, or alias them on `body` or below: an alias on `:root` is worked out before the variable exists there. `primary` is the colour of the built-in accent (`text-primary`, the progress bar). In a component, `inject(THEME_CONFIG)` from `slide-ng/lib/theme-config` gives the whole map, lists and objects too. There is one value for both colour modes, so a theme that wants another dark colour can offer a second key, such as `primaryDark`, and use it under `html.dark`. The rules for values are in [Themes and addons](./themes.md#theme-settings). + Keys other than `name`, `headmatter` and `layouts` are not read, and the generator says so: settings such as `colorSchema` and `fonts` go under `headmatter`. A value of the wrong type is reported and ignored. A deck's own folder can have a `theme.json` too, to describe the inputs and slots of its own layouts. -Pictures go in `public/`. +Pictures go in `public/`. Translations of slide.ng's interface go in `locales/.json`, see [Themes and addons](./themes.md#translating-the-interface). ## A footer or page number @@ -114,7 +129,7 @@ A theme is a folder, so publish it as an npm package with these folders at the t "version": "1.0.0", "license": "MIT", "keywords": ["slide-ng-theme", "slide-ng"], - "files": ["layouts", "components", "layers", "styles", "public", "setup", "theme.json", "uno.config.mjs"], + "files": ["layouts", "components", "layers", "styles", "public", "setup", "locales", "theme.json", "uno.config.mjs"], "peerDependencies": { "@slide-ng/core": "*" } } ``` diff --git a/src/content/features/interface-language.md b/src/content/features/interface-language.md new file mode 100644 index 0000000..44fa20a --- /dev/null +++ b/src/content/features/interface-language.md @@ -0,0 +1,78 @@ +--- +title: Interface language +description: Show the bar, the menus and the presenter in the deck's language, and translate them with a JSON file. +--- + +# Interface language + +slide.ng's own interface is in English: the bar and its tooltips, the settings menu, the overview, the go-to box, the right-click menu, the presenter, the info dialog and the drawing toolbar. The headmatter's `lang` picks another language. Turkish is built in. + +```md +--- +lang: tr # , the interface in Turkish, dates and numbers written the Turkish way +uiLang: en # optional: the interface in another language than the slides +--- +``` + +| Key | What it does | +| --- | --- | +| `lang` | The language of the deck: ``, the interface language and the locale of the `date`, `number`, `currency` and `percent` pipes. | +| `uiLang` | The interface language only. It wins over `lang`. | + +A tag is written the usual way: `pt_br` is read as `pt-BR`. Without either key the interface is English. + +## Translate it + +For a language that is not built in, put `locales/.json` next to `slides.md`. It is flat JSON, with the keys you translate: + +```json +{ "nav.next": "Nächste Folie", "presenter.noNotes": "Keine Notizen für Folie {no}." } +``` + +The keys and their English text are listed in [UI-STRINGS.md](https://github.com/slide-ng/slide.ng/blob/main/docs/UI-STRINGS.md) in the slide.ng repository. Keep the `{name}` placeholders, in any order the sentence needs. + +- A key that no file translates stays English, and so does a language without a file. +- A theme or an addon can have a `locales/` folder too. The built-in translations come first, then the theme, the addons and the deck, key by key, so a deck can change one text of its theme. See [Themes and addons](../customize/themes.md#translating-the-interface). +- In each folder the shorter tag is read first: `de.json`, then `de-AT.json`. +- The generator warns about a key that does not exist, a value that is not text and a placeholder that was lost or added. That key stays English. A file that is not JSON stops the build. + +## Dates and numbers + +`lang` also sets Angular's `LOCALE_ID`, so the pipes in a slide write for that language: + +```md +{{ 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. + +## Right to left + +`ar`, `he`, `fa` and `ur` set `dir="rtl"` on the page, unless `htmlAttrs.dir` says otherwise. The bar, the menus, the go-to box and the presenter are mirrored. + +## One deck in several languages + +Write one entry file per language, and import the slides that are the same in every language with `src:`: + +``` +slides.md lang: en +slides.tr.md lang: tr, its own translated slides, and src: ./pages/demo.md for a shared one +pages/demo.md +``` + +Build each into its own folder: + +```sh +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. `SLIDE_NG_LANG` does the same. See the [CLI reference](../built-in/cli.md). + +## 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 arrow keys, swipes and the position of the drawing toolbar are not mirrored. +- The language cannot be switched while presenting. Build one deck per language instead. +- 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. diff --git a/src/content/features/routing.md b/src/content/features/routing.md index 83eefb0..211fd17 100644 --- a/src/content/features/routing.md +++ b/src/content/features/routing.md @@ -17,7 +17,7 @@ routeAlias: intro --- ``` -Now `/intro` opens the slide. `` links to it, see [Components](../built-in/components.md). +Now `/intro` opens the slide. `` links to it, see [Components](../built-in/components.md), and so does the markdown link `[intro](/intro)`, see [Links](../guide/syntax.md#links). ## Hash or history diff --git a/src/content/features/seo-meta.md b/src/content/features/seo-meta.md index e54bc59..0c73e5a 100644 --- a/src/content/features/seo-meta.md +++ b/src/content/features/seo-meta.md @@ -29,7 +29,7 @@ seoMeta: | `title`, `titleTemplate` | The browser tab. `%s` is the title. | | `info` | Markdown for the info dialog. With the markup taken out and cut at 300 characters, it is also the page description and the PDF's subject. | | `author`, `keywords` | Meta tags. `keywords` is a list or a comma separated text. | -| `lang`, `htmlAttrs` | Attributes on ``. | +| `lang`, `htmlAttrs` | Attributes on ``. `lang` also picks the [interface language](./interface-language.md) and the locale of dates and numbers, and `ar`, `he`, `fa` and `ur` add `dir="rtl"` unless `htmlAttrs.dir` is set. | | `favicon` | A file of `public/`, or a web address. | | `seoMeta` | Open Graph and Twitter tags: `ogTitle`, `ogDescription`, `ogImage`, `ogUrl`, `twitterCard` and so on. | diff --git a/src/content/features/speaker-notes.md b/src/content/features/speaker-notes.md index d8591b6..0146259 100644 --- a/src/content/features/speaker-notes.md +++ b/src/content/features/speaker-notes.md @@ -18,4 +18,5 @@ In a note, `[click]` marks where the next click starts, and `[click:3]` moves th - `/notes` shows only the notes and follows the presenter. - `slide-ng export-notes` writes a PDF of the notes. - `slide-ng build --without-notes` leaves the notes out of the built site. +- A link to a web page in a note opens a new tab, so the presenter view stays. A link to a slide stays a plain address, and a click on it loads that page. - The notes are plain text. Ruby annotations for Japanese (`notesAutoRuby`) are not supported. diff --git a/src/content/features/table-of-contents.md b/src/content/features/table-of-contents.md index de3d088..9bb90b6 100644 --- a/src/content/features/table-of-contents.md +++ b/src/content/features/table-of-contents.md @@ -23,4 +23,4 @@ Leave a slide out with `hideInToc: true`. | `minDepth`, `maxDepth` | Which levels to list. | | `mode` | `all`, `onlyCurrentTree` (the path to the current slide and what is below it) or `onlySiblings` (the lists that contain the current slide). | -The slide's title is plain text: the markup of links, code and HTML tags in a heading is taken out, also in the tab title, the go-to box and the PDF outline. `$math$` in a title is drawn with KaTeX here. Slidev's `TitleRenderer`, which shows a title as HTML, is not there. +The list shows each title as HTML: inline markdown such as `**bold**` and `code` is drawn, and `$math$` with KaTeX. Raw HTML in a title is shown as text. `` shows one title the same way anywhere, see [Components](../built-in/components.md). The tab title, the go-to box and the PDF outline use the plain text, with the markup taken out. diff --git a/src/content/guide/export.md b/src/content/guide/export.md index bbfd148..645ae91 100644 --- a/src/content/guide/export.md +++ b/src/content/guide/export.md @@ -26,6 +26,10 @@ Export opens the deck in Chromium. slide.ng never downloads a browser, so set `C In a PDF, a slide that has clicks shows its last state. `--with-clicks` makes a page for every click step. A `@defer` block that waits (`on timer`, `on viewport`) may still show its placeholder when the page is captured: give `export` a `--wait`. `` shows content only on paper, see [Components](../built-in/components.md). +## Links in a PDF + +A link to a slide, written in markdown (`[x](5)`) or as ``, points at the first page of that slide in the PDF, so a click jumps there instead of opening the local server's address. It works only when the target slide is in the same file: with `--per-slide`, or with a `--range` that leaves the slide out, a link to another slide is no link. Links to web pages stay links. + ## Choosing slides and looks ```sh diff --git a/src/content/guide/styling.md b/src/content/guide/styling.md index d8c3709..f5e57c5 100644 --- a/src/content/guide/styling.md +++ b/src/content/guide/styling.md @@ -42,4 +42,4 @@ The core styles follow Slidev's: code is 12px (`--slidev-code-font-size`), and t ## Shortcuts and icons -slide.ng defines a few of Slidev's utility shortcuts, such as `bg-main`, `text-primary` and `border-main`. Icons are classes or tags, see [Icons](../features/icons.md). A theme or deck can add its own UnoCSS settings in `uno.config.mjs`, see [Directory structure](../customize/directory-structure.md). +slide.ng defines a few of Slidev's utility shortcuts, such as `bg-main`, `text-primary` and `border-main`. `themeConfig: { primary: '#5d8392' }` in the headmatter changes the colour of `text-primary`, see [Theme settings](../customize/themes.md#theme-settings). Icons are classes or tags, see [Icons](../features/icons.md). A theme or deck can add its own UnoCSS settings in `uno.config.mjs`, see [Directory structure](../customize/directory-structure.md). diff --git a/src/content/guide/syntax.md b/src/content/guide/syntax.md index 3d887c4..8648650 100644 --- a/src/content/guide/syntax.md +++ b/src/content/guide/syntax.md @@ -42,6 +42,27 @@ The last HTML comment of a slide is its speaker note. It is stored with the slid ``` +## Links + +As in Slidev, a markdown link to a slide moves inside the deck, and a link to a web page opens a new tab: + +```md +[go to slide 5](5), or [5](/5), [5](./5), [5](#/5) +[pricing](/pricing) goes to the slide with routeAlias: pricing +[results](#results) goes to a heading of this slide +[the docs](https://example.org) opens in a new tab +``` + +- An address of only digits, or `/`, `./` or `#/` followed by a slide number or a `routeAlias`, becomes a ``. A click moves to that slide without loading the page again, with history or hash routing, a base or an offline folder. Ctrl or Cmd + click opens it in a new tab. A number past the last slide goes to the last slide. +- Other addresses that start with `/` or `./`, such as `/file.pdf` or a name that is no `routeAlias`, stay plain links. +- `#id` and `./#id` scroll to that element of the slide. `#5` is such an anchor too: write `5` or `#/5` for slide 5. +- An `http:` or `https:` address gets `target="_blank" rel="noopener"`. `mailto:` and other links stay as they are. +- An `` written as HTML is left as written. Use `` for a link to a slide in HTML. +- In speaker notes a web page opens a new tab too, but a link to a slide stays a plain address. +- In an exported PDF a link to a slide points at that slide's page, see [Export](./export.md#links-in-a-pdf). + +The differences with Slidev are on the [differences page](../migrating/from-slidev.md). + ## Slots A line with only `::name::` starts a named part of the slide, which a layout can place somewhere: diff --git a/src/content/migrating/from-slidev.md b/src/content/migrating/from-slidev.md index 5639ec2..c083675 100644 --- a/src/content/migrating/from-slidev.md +++ b/src/content/migrating/from-slidev.md @@ -24,7 +24,8 @@ slide.ng reads the same markdown file format as *Slidev, with the same slide spl | `