@slidev/docs 51.6.2

package/guide/exporting.md

@@ -0,0 +1,240 @@
+---
+outline: deep
+---
+
+# Exporting
+
+Usually the slides are displayed in a web browser, but you can also export them to PDF, PPTX, PNG, or Markdown files for sharing or printing. This feature is available through the CLI command [`slidev export`](../builtin/cli#export).
+
+However, interactive features in your slides may not be available in the exported files. You can build and host your slides as a web application to keep the interactivity. See [Building and Hosting](./hosting) for more information.
+
+## The Browser Exporter <Badge> Recommended </Badge> {#browser}
+
+> Available since v0.50.0-beta.11
+
+Slidev provides a UI in the browser for exporting your slides. You can access it by clicking the "Export" button in "More options" menu in the [navigation bar](./ui#navigation-bar), or go to `http://localhost:<port>/export` directly.
+
+In the UI, you can export the slides as PDF, or capture the slides as images and download them as a PPTX or zip file.
+
+Note that browsers other than **modern Chromium-based browsers** may not work well with the exporting UI. If you encounter any issues, please try use the CLI instead.
+
+> The following content of this page is for the CLI only.
+
+## The CLI {#cli}
+
+Exporting to PDF, PPTX, or PNG relies on [Playwright](https://playwright.dev) for rendering the slides. Therefore [`playwright-chromium`](https://npmjs.com/package/playwright-chromium) is required to be installed in your project:
+
+::: code-group
+
+```bash [pnpm]
+$ pnpm add -D playwright-chromium
+```
+
+```bash [npm]
+$ npm i -D playwright-chromium
+```
+
+```bash [yarn]
+$ yarn add -D playwright-chromium
+```
+
+```bash [bun]
+$ bun add -D playwright-chromium
+```
+
+:::
+
+## Formats
+
+### PDF
+
+After installing `playwright-chromium` as described above, you can export your slides to PDF using the following command:
+
+```bash
+$ slidev export
+```
+
+By default, the PDF will be placed at `./slides-export.pdf`.
+
+### PPTX
+
+Slidev can also export your slides as a PPTX file:
+
+```bash
+$ slidev export --format pptx
+```
+
+Note that all the slides in the PPTX file will be exported as images, so the text will not be selectable. Presenter notes will be conveyed into the PPTX file on a per-slide basis.
+
+In this mode, the `--with-clicks` option is enabled by default. To disable it, pass `--with-clicks false`.
+
+### PNGs and Markdown
+
+When passing in the `--format png` option, Slidev will export PNG images for each slide instead of a PDF:
+
+```bash
+$ slidev export --format png
+```
+
+You can also compile a markdown file composed of compiled png using `--format md`:
+
+```bash
+$ slidev export --format md
+```
+
+## Options
+
+Here are some common options you can use with the `slidev export` command. For a full list of options, see the [CLI documentation](../builtin/cli#export).
+
+### Export Clicks Steps
+
+By default, Slidev exports one page per slide with clicks animations disabled. If you want to export slides with multiple steps into multiple pages, pass the `--with-clicks` option:
+
+```bash
+$ slidev export --with-clicks
+```
+
+### Output Filename
+
+You can specify the output filename with the `--output` option:
+
+```bash
+$ slidev export --output my-pdf-export
+```
+
+Or in the headmatter configuration:
+
+```yaml
+---
+exportFilename: my-pdf-export
+---
+```
+
+### Export with Range
+
+By default, all slides in the presentation are exported. If you want to export a specific slide or a range of slides you can set the `--range` option and specify which slides you would like to export:
+
+```bash
+$ slidev export --range 1,6-8,10
+```
+
+This option accepts both specific slide numbers and ranges. The example above would export slides 1,6,7,8 and 10.
+
+### Multiple Exports
+
+You can also export multiple slides at once:
+
+```bash
+$ slidev export slides1.md slides2.md
+```
+
+Or (only available in certain shells):
+
+```bash
+$ slidev export *.md
+```
+
+In this case, each input file will generate its own PDF file.
+
+### Dark Mode
+
+In case you want to export your slides using the dark version of the theme, use the `--dark` option:
+
+```bash
+$ slidev export --dark
+```
+
+### Timeouts
+
+For big presentations, you might want to increase the Playwright timeout with `--timeout`:
+
+```bash
+$ slidev export --timeout 60000
+```
+
+### Wait
+
+Some parts of your slides may require a longer time to render. You can use the `--wait` option to have an extra delay before exporting:
+
+```bash
+$ slidev export --wait 10000
+```
+
+There is also a `--wait-until` option to wait for a state before exporting each slide. If you keep encountering timeout issues, you can try setting this option:
+
+```bash
+$ slidev export --wait-until none
+```
+
+Possible values:
+
+- `'networkidle'` - (_default_) consider operation to be finished when there are no network connections for at least `500` ms. This is the safest, but may cause timeouts.
+- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
+- `'load'` - consider operation to be finished when the `load` event is fired.
+- `'none'` - do not wait for any event.
+
+::: warning
+When specifying values other than `'networkidle'`, please make sure the printed slides are complete and correct. If some contents are missing, you may need to use the `--wait` option.
+:::
+
+### Executable Path
+
+Chromium may miss some features like codecs that are required to decode some videos. You can set the browser executable path for Playwright to your Chrome or Edge using `--executable-path`:
+
+```bash
+$ slidev export --executable-path [path_to_chromium]
+```
+
+### PDF Outline
+
+> Available since v0.36.10
+
+You can generate the PDF outline by passing the `--with-toc` option:
+
+```bash
+$ slidev export --with-toc
+```
+
+### Omit Background
+
+When exporting to PNGs, you can remove the default browser background by passing `--omit-background`:
+
+```bash
+$ slidev export --omit-background
+```
+
+The default browser background is the white background visible on all browser windows and is different than other backgrounds applied throughout the application using CSS styling. [See Playwright docs](https://playwright.dev/docs/api/class-page#page-screenshot-option-omit-background). You will then need to apply additional CSS styling to the application to reveal the transparency.
+
+Here is a basic example that covers all backgrounds in the application:
+
+```css
+* {
+  background: transparent !important;
+}
+```
+
+## Troubleshooting
+
+### Missing Content or Animation not Finished
+
+If you find that some content is missing or the animations are not finished in the exported PDF, you can try adding a wait time before exporting each slide:
+
+```bash
+$ slidev export --wait 1000
+```
+
+### Broken Emojis
+
+If the PDF or PNG are missing Emojis, you are likely missing required fonts (such as. e.g. [Google's _Noto Emoji_](https://fonts.google.com/noto/specimen/Noto+Emoji)) in your environment.
+
+This can affect e.g. CI/CD-like in-container sort of Linux environments. It can be fixed e.g. like this:
+
+```bash
+$ curl -L --output NotoColorEmoji.ttf https://github.com/googlefonts/noto-emoji/raw/main/fonts/NotoColorEmoji.ttf
+$ sudo mv NotoColorEmoji.ttf /usr/local/share/fonts/
+$ fc-cache -fv
+```
+
+### Wrong Context in Global Layers
+
+See the tip in https://sli.dev/features/global-layers.

package/guide/faq.md

@@ -0,0 +1,134 @@
+---
+outline: deep
+---
+
+# FAQ
+
+## Assets Handling {#assets-handling}
+
+You may use static assets like images and videos in your slides. Since Slidev is based on Vite, you can import them directly in your markdown files.
+
+URLs that can be statically analyzed as assets can use relative paths:
+
+```md
+![alt](./image.png)
+<img src="./image.png" />
+```
+
+In the above case, the URLs will be resolved to `/BASE_URL/assets/image.png` after build.
+
+However, relative paths in frontmatter and other components will be broken after build:
+
+```md
+---
+background: ./image.png  # Broken after build
+---
+
+<Comp src="./image.png" />
+```
+
+In the above case, the URLs are not statically analyzable and will be preserved as-is, which will result in 404 errors after build.
+
+To solve this, you can place these assets in the [public folder](../custom/directory-structure#public) and use an absolute path to import them:
+
+```md
+---
+background: /image.png
+---
+
+<Comp src="/image.png" />
+```
+
+For more details, refer to [Vite's documentation](https://vitejs.dev/guide/assets.html).
+
+## Positioning {#positioning}
+
+Since Slidev is web-based, CSS is the primary way to position elements. Here are some useful tips for position elements:
+
+### Grids And Flexboxes
+
+You can use CSS Grids to create complex layouts:
+
+::: code-group
+
+```md [Two columns]
+<div class="grid grid-cols-2 gap-4">
+  <div>
+    The first column
+  </div>
+  <div>
+    The second column
+  </div>
+</div>
+```
+
+```md [Complex case]
+<div class="grid grid-cols-[200px_1fr_10%] gap-4">
+  <div>
+    The first column (200px)
+  </div>
+  <div>
+    The second column (auto fit)
+  </div>
+  <div>
+    The third column (10% width to parent container)
+  </div>
+</div>
+```
+
+:::
+
+And use Flexboxes to create more responsive layouts:
+
+::: code-group
+
+```md [Horizontal]
+<div class="flex items-center">
+  <div>
+    First block
+  </div>
+  <div>
+    Second block
+  </div>
+</div>
+```
+
+```md [Vertical]
+<div class="flex flex-col items-center">
+  <div>
+    Centered content
+  </div>
+</div>
+```
+
+:::
+
+Learn more: [CSS Grids](https://css-tricks.com/snippets/css/complete-guide-grid/), [flexboxes](https://css-tricks.com/snippets/css/a-guide-to-flexbox/), or even [Masonry](https://css-tricks.com/native-css-masonry-layout-in-css-grid/).
+
+### Absolute Position
+
+You can use UnoCSS to position elements absolutely:
+
+```md
+<div class="absolute left-30px bottom-30px">
+  This is a left-bottom aligned footer
+</div>
+```
+
+Or use the draggable elements feature:
+
+<LinkCard link="features/draggable" />
+
+## Adjust Sizes {#adjust-size}
+
+- Adjust all slides's size:
+
+<LinkCard link="features/canvas-size" />
+
+- Adjust several slides' size:
+
+<LinkCard link="features/zoom-slide" />
+
+- Adjust some elements' size:
+
+<LinkCard link="features/transform-component" />

package/guide/global-context.md

@@ -0,0 +1,169 @@
+# Global Context
+
+Slidev injects several global context values for advanced navigation controls.
+
+## Direct Usage {#direct-usage}
+
+You can access them directly in your slides or components:
+
+```md
+<!-- slides.md -->
+
+# Page 1
+
+Current page is: {{ $nav.currentPage }}
+```
+
+```vue
+<!-- Foo.vue -->
+
+<template>
+  <div>Title: {{ $slidev.configs.title }}</div>
+  <button @click="$nav.next">
+    Next Click
+  </button>
+  <button @click="$nav.nextSlide">
+    Next Slide
+  </button>
+</template>
+```
+
+## Composable Usage {#composable-usage}
+
+> Available since v0.48.0
+
+If you want to get the context programmatically (also type-safely), you can import composables from `@slidev/client`:
+
+```vue
+<script setup>
+import { onSlideEnter, onSlideLeave, useDarkMode, useIsSlideActive, useNav, useSlideContext } from '@slidev/client'
+
+const { $slidev } = useSlideContext()
+const { currentPage, currentLayout, currentSlideRoute } = useNav()
+const { isDark } = useDarkMode()
+const isActive = useIsSlideActive()
+onSlideEnter(() => { /* ... */ })
+onSlideLeave(() => { /* ... */ })
+// ...
+</script>
+```
+
+> [!NOTE]
+> Previously, you might see the usage of importing nested modules like `import { isDark } from '@slidev/client/logic/dark.ts'`, this is **NOT RECOMMENDED** as they are internal implementation details and may change in the future. Always use the public APIs from `@slidev/client` if possible.
+
+::: warning
+
+When the `useSlideContext` composable is used in a file, the automatic injection of `$slidev` will be disabled. You need to manually get the `$slidev` object to the `useSlideContext` function.
+
+:::
+
+<SeeAlso :links="['features/slide-hook']" />
+
+## Properties {#properties}
+
+### `$slidev` {#slidev}
+
+The global context object.
+
+### `$frontmatter` {#frontmatter}
+
+The frontmatter object of the current slide. Note that this is empty for components out of the slides like <LinkInline link="features/global-layers" />.
+
+### `$clicks` {#clicks}
+
+`$clicks` hold the number of clicks on the current slide. Can be used conditionally to show different content on clicks.
+
+```html
+<div v-if="$clicks > 3">Content</div>
+```
+
+See the <LinkInline link="guide/animations" /> guide for more information.
+
+### `$nav` {#nav}
+
+A reactive object holding the properties and controls of the slide navigation. For examples:
+
+```js
+$nav.next() // go next step
+$nav.nextSlide() // go next slide (skip clicks)
+$nav.go(10) // go slide #10
+
+$nav.currentPage // current slide number
+$nav.currentLayout // current layout name
+```
+
+For more properties available, refer to the [`SlidevContextNav` interface](https://github.com/slidevjs/slidev/blob/main/packages/client/composables/useNav.ts).
+
+### `$page` {#page}
+
+`$page` holds the number of the current page, 1-indexed.
+
+```md
+Page: {{ $page }}
+
+Is current page active: {{ $page === $nav.currentPage }}
+```
+
+> [!Note] > `$nav.clicks` is a global state while `$clicks` is the local clicks number for each slide.
+
+### `$renderContext` {#render-context}
+
+`$renderContext` holds the current render context, which can be `slide`, `overview`, `presenter` or `previewNext`
+
+```md
+<div v-if="['slide', 'presenter'].includes($renderContext)">
+  This content will only be rendered in main slides view
+</div>
+```
+
+You can also use the [`<RenderWhen>` component](../builtin/components#renderwhen).
+
+### `$slidev.configs` {#configs}
+
+A reactive object holding the configurations for the slide project. For example:
+
+```md
+---
+title: My First Slidev!
+---
+
+# Page 1
+
+---
+
+# Any Page
+
+{{ $slidev.configs.title }} // 'My First Slidev!'
+```
+
+### `$slidev.themeConfigs` {#theme-configs}
+
+A reactive object holding the parsed theme configurations:
+
+```yaml
+---
+title: My First Slidev!
+themeConfig:
+  primary: '#213435'
+---
+```
+
+Then the theme can access the primary color like:
+
+```md
+{{ $slidev.themeConfigs.primary }} // '#213435'
+```
+
+## Types {#types}
+
+If you want to get a type programmatically, you can import types like `TocItem` from `@slidev/types`:
+
+```vue
+<script setup>
+import type { TocItem } from '@slidev/types'
+
+function tocFunc(tree: TocItem[]): TocItem[] {
+  // ...
+}
+</script>
+```