@slidev/docs 51.6.2

package/custom/index.md

@@ -0,0 +1,192 @@
+# Customizations
+
+Slidev is fully customizable, from styling to tooling configurations. It allows you to configure the tools underneath ([Vite](/custom/config-vite), [UnoCSS](/custom/config-unocss), [Monaco](/custom/config-monaco), etc.)
+
+## Slides Deck Configs {#headmatter}
+
+You can configure the whole slides project in the frontmatter of your **first** slide (i.e. headmatter). The following shows the default value for each option:
+
+```yaml
+---
+# theme id, package name, or local path
+# Learn more: https://sli.dev/guide/theme-addon.html#use-theme
+theme: default
+# addons, can be a list of package names or local paths
+# Learn more: https://sli.dev/guide/theme-addon.html#use-addon
+addons: []
+# title of your slide, will inferred from the first header if not specified
+title: Slidev
+# titleTemplate for the webpage, `%s` will be replaced by the slides deck's title
+titleTemplate: '%s - Slidev'
+# information for your slides, can be a Markdown string
+info: false
+# author field for exported PDF or PPTX
+author: Your Name Here
+# keywords field for exported PDF, comma-delimited
+keywords: keyword1,keyword2
+
+# enable presenter mode, can be boolean, 'dev' or 'build'
+presenter: true
+# enable browser exporter, can be boolean, 'dev' or 'build'
+browserExporter: dev
+# enabled pdf downloading in SPA build, can also be a custom url
+download: false
+# filename of the export file
+exportFilename: slidev-exported
+# export options
+# use export CLI options in camelCase format
+# Learn more: https://sli.dev/guide/exporting.html
+export:
+  format: pdf
+  timeout: 30000
+  dark: false
+  withClicks: false
+  withToc: false
+# enable twoslash, can be boolean, 'dev' or 'build'
+twoslash: true
+# show line numbers in code blocks
+lineNumbers: false
+# enable monaco editor, can be boolean, 'dev' or 'build'
+monaco: true
+# Where to load monaco types from, can be 'cdn', 'local' or 'none'
+monacoTypesSource: local
+# explicitly specify extra local packages to import the types for
+monacoTypesAdditionalPackages: []
+# explicitly specify extra local modules as dependencies of monaco runnable
+monacoRunAdditionalDeps: []
+# download remote assets in local using vite-plugin-remote-assets, can be boolean, 'dev' or 'build'
+remoteAssets: false
+# controls whether texts in slides are selectable
+selectable: true
+# enable slide recording, can be boolean, 'dev' or 'build'
+record: dev
+# enable Slidev's context menu, can be boolean, 'dev' or 'build'
+contextMenu: true
+# enable wake lock, can be boolean, 'dev' or 'build'
+wakeLock: true
+# take snapshot for each slide in the overview
+overviewSnapshots: false
+
+# force color schema for the slides, can be 'auto', 'light', or 'dark'
+colorSchema: auto
+# router mode for vue-router, can be "history" or "hash"
+routerMode: history
+# aspect ratio for the slides
+aspectRatio: 16/9
+# real width of the canvas, unit in px
+canvasWidth: 980
+# used for theme customization, will inject root styles as `--slidev-theme-x` for attribute `x`
+themeConfig:
+  primary: '#5d8392'
+
+# favicon, can be a local file path or URL
+favicon: 'https://cdn.jsdelivr.net/gh/slidevjs/slidev/assets/favicon.png'
+# URL of PlantUML server used to render diagrams
+# Learn more: https://sli.dev/features/plantuml.html
+plantUmlServer: https://www.plantuml.com/plantuml
+# fonts will be auto-imported from Google fonts
+# Learn more: https://sli.dev/custom/config-fonts.html
+fonts:
+  sans: Roboto
+  serif: Roboto Slab
+  mono: Fira Code
+
+# default frontmatter applies to all slides
+defaults:
+  layout: default
+  # ...
+
+# drawing options
+# Learn more: https://sli.dev/guide/drawing.html
+drawings:
+  enabled: true
+  persist: false
+  presenterOnly: false
+  syncAll: true
+
+# HTML tag attributes
+htmlAttrs:
+  dir: ltr
+  lang: en
+
+# SEO meta tags
+seoMeta:
+  ogTitle: Slidev Starter Template
+  ogDescription: Presentation slides for developers
+  ogImage: https://cover.sli.dev
+  ogUrl: https://example.com
+  twitterCard: summary_large_image
+  twitterTitle: Slidev Starter Template
+  twitterDescription: Presentation slides for developers
+  twitterImage: https://cover.sli.dev
+  twitterSite: username
+  twitterUrl: https://example.com
+---
+```
+
+Check out the [type definitions](https://github.com/slidevjs/slidev/blob/main/packages/types/src/config.ts) for more details.
+
+## Per-slide Configs {#frontmatter}
+
+Also every slide accepts the following configuration in its frontmatter block. The following shows the default value for each option:
+
+```yaml
+---
+# custom clicks count
+# Learn more: https://sli.dev/guide/animations.html#custom-total-clicks-count
+clicks: 0
+# custom start clicks count
+clicksStart: 0
+# completely disable and hide the slide
+disabled: false
+# the same as `disabled`
+hide: false
+# hide the slide for the <Toc> components
+hideInToc: false
+# defines the layout component applied to the slide
+layout: <"cover" if the slide is the first slide, otherwise "default">
+# override the title level for the <TitleRenderer> and <Toc> components
+# only if `title` has also been declared
+level: 1
+# mount this slide before entering
+preload: true
+# create a route alias that can be used in the URL or with the <Link> component
+routeAlias: undefined # or string
+# includes a markdown file
+# Learn more: https://sli.dev/guide/syntax.html#importing-slides
+src: undefined # or string
+# override the title for the <TitleRenderer> and <Toc> components
+# only if `title` has also been declared
+title: undefined # or string
+# defines the transition between the slide and the next one
+# Learn more: https://sli.dev/guide/animations.html#slide-transitions
+transition: undefined # or BuiltinSlideTransition | string | TransitionGroupProps | null
+# custom zoom scale
+# useful for slides with a lot of content
+zoom: 1
+# used as positions of draggable elements
+# Learn more: https://sli.dev/features/draggable.html
+dragPos: {} # type: Record<string, string>
+---
+```
+
+Check out the [type definition](https://github.com/slidevjs/slidev/blob/main/packages/types/src/frontmatter.ts#L260) for more details.
+
+## Directory Structure
+
+Slidev uses directory structure conventions to minimalize the configuration surface and make extensions in functionality flexible and intuitive.
+
+Refer to the [Directory Structure](/custom/directory-structure) section.
+
+## Config Tools
+
+<script setup>
+import VPLink from 'vitepress/dist/client/theme-default/components/VPLink.vue'
+import customizations from '../.vitepress/customizations'
+</script>
+
+<li v-for="c of customizations.slice(2)" :key="c.text">
+  <VPLink :href="c.link">
+    {{ c.text }}
+  </VPLink>
+</li>

package/features/block-frontmatter.md

@@ -0,0 +1,39 @@
+---
+depends:
+  - guide/syntax
+relates:
+  - features/prettier-plugin
+tags: [syntax]
+description: |
+  Use a YAML code block as the frontmatter.
+---
+
+# Block Frontmatter
+
+The usual way to define frontmatters of slides is concise, but may lack of highlighting and formatter support. To solve this, you can use a YAML block at the very beginning of the slide content as the frontmatter of the slide:
+
+````md
+---
+theme: default
+---
+
+# Slide 1
+
+---
+
+```yaml
+layout: quote
+```
+
+# Slide 2
+
+---
+
+# Slide 3
+````
+
+::: warning About headmatter
+
+Headmatter in Slidev is exactly the usual called "frontmatter" of the a Markdown file, which is supported by most of the Markdown editors and formatters. So you can't use a YAML block as the headmatter of the whole slide deck.
+
+:::

package/features/build-with-pdf.md

@@ -0,0 +1,42 @@
+---
+depends:
+  - guide/exporting
+  - guide/hosting
+relates:
+  - CLI export options: /builtin/cli#export
+  - Headmatter export options: /custom/#headmatter
+tags: [export, build]
+description: |
+  Generate a downloadable PDF along with your slides build.
+---
+
+# Generate PDF when Building
+
+You can provide a downloadable PDF in your built slides with the following config in headmatter:
+
+```md
+---
+download: true
+---
+```
+
+Slidev will generate a PDF file along with the build, and a download button will be displayed in the build.
+
+You can also provide a custom URL for the PDF. In that case, the rendering process will be skipped.
+
+```md
+---
+download: 'https://myside.com/my-talk.pdf'
+---
+```
+
+This can also be done with the CLI option `--download` (`boolean` only).
+
+```bash
+$ slidev build --download
+```
+
+When using the download option, you can also provide the export options via:
+
+- [CLI export options](/builtin/cli#export)
+- [Headmatter export options](/custom/#frontmatter-configures)

package/features/bundle-remote-assets.md

@@ -0,0 +1,29 @@
+---
+relates:
+  - vite-plugin-remote-assets: https://github.com/antfu/vite-plugin-remote-assets
+tags: [build]
+description: |
+  Download and bundle remote assets when building your slides.
+---
+
+# Bundle Remote Assets
+
+Just like you would do in markdown, you can use images pointing to a remote or local URL.
+
+For remote assets, the built-in [`vite-plugin-remote-assets`](https://github.com/antfu/vite-plugin-remote-assets) will cache them onto the disk at first run, ensuring instant loading even for large images later on.
+
+```md
+![Remote Image](https://sli.dev/favicon.png)
+```
+
+For local assets, put them into the [`public` folder](/custom/directory-structure.html#public) and reference them with a **leading slash** (i.e., `/pic.png`, NOT `./pic.png`, which is relative to the working file).
+
+```md
+![Local Image](/pic.png)
+```
+
+If you want to apply custom sizes or styles, you can convert them to the `<img>` tag:
+
+```html
+<img src="/pic.png" class="m-40 h-40 rounded shadow" />
+```

package/features/canvas-size.md

@@ -0,0 +1,32 @@
+---
+relates:
+  - guide/faq#adjust-size
+  - features/zoom-slide
+  - features/transform-component
+tags: [layout]
+description: |
+  Set the size for all your slides.
+---
+
+# Slide Canvas Size
+
+Slidev allows you to set the size of the slide canvas via the `canvasWidth` and `aspectRatio` options in the headmatter:
+
+```md
+---
+# aspect ratio for the slides
+aspectRatio: 16/9
+# real width of the canvas, unit in px
+canvasWidth: 980
+---
+
+# Your slides here
+```
+
+To scale several slides in your presentation, you can use the `zoom` option:
+
+<LinkCard link="features/zoom-slide" />
+
+To adjust the size of some elements on your slides, you can use the `Transform` component:
+
+<LinkCard link="features/transform-component" />

package/features/click-marker.md

@@ -0,0 +1,31 @@
+---
+depends:
+  - guide/syntax#notes
+  - guide/animations
+since: v0.48.0
+tags: [presenter, animation]
+description: |
+  Highlighting notes and auto-scrolling to the active section of notes.
+---
+
+# Click Markers
+
+For some slides you may have longer notes that could be hard to find your place. Slidev supports click markers that allow highlighting and auto-scrolling to the section of notes from your corresponding content. Put `[click]` markers at the beginning of any line in your notes for the timing you need to go to another [click](/guide/animations#click-animation). You may skip `n` clicks by using `[click:{n+1}]`. For example:
+
+```md
+<!--
+Content before the first click
+
+[click] This will be highlighted after the first click
+
+Also highlighted after the first click
+
+- [click] This list element will be highlighted after the second click
+
+[click:3] Last click (skip two clicks)
+-->
+```
+
+Slidev divides the content between the click markers and highlights it in presenter notes, synchronized with your slide progress.
+
+<video src="https://github.com/slidevjs/slidev/assets/11247099/40014e34-67cd-4830-8c8d-8431754a3672" controls rounded shadow w-full></video>

package/features/code-block-line-numbers.md

@@ -0,0 +1,32 @@
+---
+depends:
+  - guide/syntax#code-block
+tags: [codeblock]
+description: |
+  Enable line numbering for all code blocks across the slides or individually.
+---
+
+# Line Numbers
+
+You can enable line numbering for all code blocks across the slides by setting `lineNumbers: true` in the headmatter, or enable each code block individually by setting `lines: true`.
+
+You can also set the starting line for each code block and highlight the lines accordingly via `{startLine: number}`, which defaults to 1.
+
+````md
+```ts {6,7}{lines:true,startLine:5}
+function add(
+  a: Ref<number> | number,
+  b: Ref<number> | number
+) {
+  return computed(() => unref(a) + unref(b))
+}
+```
+````
+
+Note that you can use `{*}` as a placeholder of <LinkInline link="features/line-highlighting" />:
+
+````md
+```ts {*}{lines:true,startLine:5}
+// ...
+```
+````

package/features/code-block-max-height.md

@@ -0,0 +1,32 @@
+---
+depends:
+  - guide/syntax#code-block
+tags: [codeblock, layout]
+description: |
+  Set a maximum height for a code block and enable scrolling.
+---
+
+# Max Height
+
+If the code doesn't fit into one slide, you use the `maxHeight` to set a fixed height and enable scrolling:
+
+````md
+```ts {2|3|7|12}{maxHeight:'100px'}
+function add(
+  a: Ref<number> | number,
+  b: Ref<number> | number
+) {
+  return computed(() => unref(a) + unref(b))
+}
+/// ...as many lines as you want
+const c = add(1, 2)
+```
+````
+
+Note that you can use `{*}` as a placeholder of <LinkInline link="features/line-highlighting" />:
+
+````md
+```ts {*}{maxHeight:'100px'}
+// ...
+```
+````

package/features/direction-variant.md

@@ -0,0 +1,31 @@
+---
+relates:
+  - UnoCSS Variants: https://unocss.dev/config/variants#variants
+since: v0.48.0
+tags: [navigation, styling]
+description: |
+  Apply different styles and animations based on the navigation direction.
+---
+
+# Navigation Direction Variants
+
+You may want to apply different classes based on whether it's navigating forward or backward. The `.slidev-nav-go-forward` or `.slidev-nav-go-backward` class will be applied to the slide container when navigating, and you can use them to apply different styles or animations:
+
+```css
+/* example: delay on only forward but not backward */
+.slidev-nav-go-forward .slidev-vclick-target {
+  transition-delay: 500ms;
+}
+.slidev-nav-go-backward .slidev-vclick-target {
+  transition-delay: 0;
+}
+```
+
+To make it easier, we also provided some [UnoCSS variants](https://github.com/slidevjs/slidev/blob/6adcf2016b8fb0cab65cf150221f1f67a76a2dd8/packages/client/uno.config.ts#L32-L38) for this. You can use the `forward:` or `backward:` prefix to any UnoCSS classes to only enable them in the specific navigation direction:
+
+```html
+<div v-click class="transition delay-300">Element</div> // [!code --]
+<div v-click class="transition forward:delay-300">Element</div> // [!code ++]
+```
+
+In the above example, the animation is only delayed when navigating forward.

package/features/draggable.md

@@ -0,0 +1,82 @@
+---
+tags: [layout]
+description: |
+  Move, resize, and rotate elements by dragging them with the mouse.
+---
+
+# Draggable Elements
+
+Draggable elements give you the ability to move, resize, and rotate elements by dragging them with the mouse. This is useful for creating floating elements in your slides.
+
+## Directive Usage
+
+### Data from the frontmatter
+
+```md
+---
+dragPos:
+  square: Left,Top,Width,Height,Rotate
+---
+
+<img v-drag="'square'" src="https://sli.dev/logo.png">
+```
+
+### Data from the directive value
+
+::: warning
+Slidev use regex to update the position value in the slide content. If you meet problems, please use the frontmatter to define the values instead.
+:::
+
+```md
+<img v-drag="[Left,Top,Width,Height,Rotate]" src="https://sli.dev/logo.png">
+```
+
+## Component Usage
+
+### Data from the frontmatter
+
+```md
+---
+dragPos:
+  foo: Left,Top,Width,Height,Rotate
+---
+
+<v-drag pos="foo" text-3xl>
+  <div class="i-carbon:arrow-up" />
+  Use the `v-drag` component to have a draggable container!
+</v-drag>
+```
+
+### Data from props
+
+```md
+<v-drag pos="Left,Top,Width,Height,Rotate" text-3xl>
+  <div class="i-carbon:arrow-up" />
+  Use the `v-drag` component to have a draggable container!
+</v-drag>
+```
+
+## Create a Draggable Element
+
+When you create a new draggable element, you don't need to specify the position value (but you need to specify the position name if you want to use the frontmatter). Slidev will automatically generate the initial position value for you.
+
+## Automatic Height
+
+You can set `Height` to `NaN` (in) or `_` (if you use the component) to make the height of the draggable element automatically adjust to its content.
+
+## Controls
+
+- Double-click the draggable element to start dragging it.
+- You can also use the arrow keys to move the element.
+- Hold `Shift` while dragging to preserve its aspect ratio.
+- Click outside the draggable element to stop dragging it.
+
+## Draggable Arrow
+
+The `<v-drag-arrow>` component creates a draggable arrow element. Simply use it like this:
+
+```md
+<v-drag-arrow />
+```
+
+And you will get a draggable arrow element. Other props are the same as [the `Arrow` component](/builtin/components#arrow).

package/features/drawing.md

@@ -0,0 +1,74 @@
+---
+depends:
+  - guide/ui#navigation-bar
+relates:
+  - drauu: https://github.com/antfu/drauu
+tags: [drawing]
+description: |
+  Draw and annotate your slides with ease.
+---
+
+# Drawing & Annotations
+
+Slidev comes with a built-in drawing and annotation feature powered by [drauu](https://github.com/antfu/drauu). It allows you to draw and annotate your slides with ease.
+
+To start, click the <carbon-pen class="inline-icon-btn"/> icon in the [navigation bar](../guide/ui#navigation-bar) to open the drawing toolbar. It's also available in the [Presenter Mode](/guide/ui#presenter-mode). Drawings and annotations you created will be **synced** automatically across all instances in real-time.
+
+<TheTweet id="1424027510342250499" />
+
+## Use with Stylus Pen
+
+When using a stylus pen on a tablet (for example, iPad with Apple Pencil), Slidev will intelligently detect the input type. You can directly draw on your slides with the pen without turning on the drawing mode while having your fingers or mouse control the navigation.
+
+## Persist Drawings
+
+The following frontmatter configuration allows you to persist your drawings as SVGs under `.slidev/drawings` directory and have them inside your exported PDF or hosted site.
+
+```md
+---
+drawings:
+  persist: true
+---
+```
+
+## Disable Drawings
+
+Entirely:
+
+```md
+---
+drawings:
+  enabled: false
+---
+```
+
+Only in Development:
+
+```md
+---
+drawings:
+  enabled: dev
+---
+```
+
+Only in Presenter Mode:
+
+```md
+---
+drawings:
+  presenterOnly: true
+---
+```
+
+## Drawing Syncing
+
+By default, Slidev syncs up your drawings across all instances. If you are sharing your slides with others, you might want to disable the syncing via:
+
+```md
+---
+drawings:
+  syncAll: false
+---
+```
+
+With this config, only the drawing from the presenter instance will be able to sync with others.

package/features/eject-theme.md

@@ -0,0 +1,27 @@
+---
+depends:
+  - guide/theme-addon
+tags: [theme, cli]
+description: |
+  Eject the installed theme from your project to customize it.
+---
+
+# Eject Theme
+
+If you want to get full control of the current theme, you can **eject** it to your local file system and modify it as you want. By running the following command
+
+```bash
+$ slidev theme eject
+```
+
+It will eject the theme you are using currently into `./theme`, and change your frontmatter to
+
+```yaml
+---
+theme: ./theme
+---
+```
+
+This could also be helpful if you want to make a theme based on an existing one. If you do, remember to mention the original theme and the author :)
+
+For more options of the `theme` command, please refer to the [Theme Command](../builtin/cli#theme) section.