## 1. Project Overview & Quickstart (slidevjs/index) # index Open-source repository slidevjs/index ### Repository Details - **Repository:** [slidevjs/index](https://github.com/slidevjs/index) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (slidevjs/docs) ## File: README.md # [sli.dev](https://sli.dev) > [!IMPORTANT] > This repository is a mirror of the `docs/` directory in [slidevjs/slidev](https://github.com/slidevjs/slidev/tree/main/docs). Mainly for other translations repositories to sync. > > **‼️ Please DO NOT submit pull requests here ‼️**. Instead, send them to the [main repository](https://github.com/slidevjs/slidev), and they will be synced here automatically. Mirrored documentation site for [Slidev](https://github.com/slidevjs/slidev) ## Translations | | Repo | Site | Maintainers | | -------------- | ---------------------------------------------- | -------------------------------: | --------------------------------------------------------------------- | | English | [docs](https://github.com/slidevjs/slidev/tree/main/docs) | [sli.dev](https://sli.dev) | [@antfu](https://github.com/antfu) | | 简体中文 | [docs-cn](https://github.com/slidevjs/docs-cn) | [cn.sli.dev](https://cn.sli.dev) | [@QC-L](https://github.com/QC-L) [@Ivocin](https://github.com/Ivocin) | | Français | [docs-fr](https://github.com/slidevjs/docs-fr) | [fr.sli.dev](https://fr.sli.dev) | [@ArthurDanjou](https://github.com/ArthurDanjou) | | Español | [docs-es](https://github.com/slidevjs/docs-es) | [es.sli.dev](https://es.sli.dev) | [@owlnai](https://github.com/owlnai) | | Русский | [docs-ru](https://github.com/slidevjs/docs-ru) | [ru.sli.dev](https://ru.sli.dev) | [@xesjkeee](https://github.com/xesjkeee) | | Việt Nam | [docs-vn](https://github.com/slidevjs/docs-vn) | [vn.sli.dev](https://vn.sli.dev) | [@bongudth](https://github.com/bongudth) | | Deutsch | [docs-de](https://github.com/slidevjs/docs-de) | [de.sli.dev](https://de.sli.dev) | [@fabiankachlock](https://github.com/fabiankachlock) | | Português (BR) | [docs-br](https://github.com/slidevjs/docs-br) | [br.sli.dev](https://br.sli.dev) | [@luisfelipesdn12](https://github.com/luisfelipesdn12) | | Ελληνικά | [docs-el](https://github.com/slidevjs/docs-el) | [el.sli.dev](https://el.sli.dev) | [@GeopJr](https://github.com/GeopJr) | | 日本語 | [docs-ja](https://github.com/slidevjs/docs-el) | [ja.sli.dev](https://ja.sli.dev) | [@IkumaTadokoro](https://github.com/IkumaTadokoro) | ## Start Server Locally ``` npm i pnpm pnpm i pnpm run dev ``` And then visit `http://localhost:3000` Or install the [Vite extension for VS Code](https://marketplace.visualstudio.com/items?itemName=antfu.vite) to edit side-by-side. ## Help on Translating See [TRANSLATIONS.md](/TRANSLATIONS.md) --- ## File: docs/custom/config-context-menu.md # Configure Context Menu Customize the context menu items in Slidev. Create `./setup/context-menu.ts` with the following content: ```ts import { defineContextMenuSetup } from '@slidev/types' import { computed } from 'vue' import Icon3DCursor from '~icons/carbon/3d-cursor' export default defineContextMenuSetup((items) => { const { isPresenter } = useNav() return computed(() => [ ...items.value, { small: false, icon: Icon3DCursor, // Used as `title` if `small` is `true` label: 'Custom Menu Item', // or a Vue component action() { alert('Custom Menu Item Clicked!') }, disabled: isPresenter.value, }, ]) }) ``` This will append a new menu item to the context menu. To disable context menu globally, set `contextMenu` to `false` in the frontmatter. `contextMenu` can also be set to `dev` or `build` to only enable the context menu in development or build mode. --- ## File: docs/custom/config-routes.md # Configure Routes Add your pages to the Slidev app. ## Usage Create `./setup/routes.ts` with the following content: ```ts import { defineRoutesSetup } from '@slidev/types' export default defineRoutesSetup((routes) => { return [ ...routes, { path: '/my-page', component: () => import('../pages/my-page.vue'), }, ] }) ``` Learn more about routes in the [Vue Router documentation](https://router.vuejs.org/). --- ## File: docs/guide/draggable.md # 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 --- ``` ### 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 ``` ## Component Usage ### Data from the frontmatter ```md --- dragPos: foo: Left,Top,Width,Height,Rotate --- Use the `v-drag` component to have a draggable container! ``` ### Data from props ```md Use the `v-drag` component to have a draggable container! ``` ## Automatic Height You can set `Height` to `NaN` (if you use the directive) or `_` (if you use the component) to make the height of the draggable element automatically adjust to its content. ## Create a Draggable Element When you first create a 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. ## 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 `` component creates a draggable arrow element. Simply use it like this: ```md ``` And you will get a draggable arrow element. Other props are the same as [the `Arrow` component](/builtin/components#arrow). --- ## File: docs/guide/overview.md # Slide Overview > Available since v0.48.0 You can visit an overview of all of your slides by clicking the button in the navigation panel and then on the top right, or by visiting `http://localhost:3030/overview` directly. The overview page gives you a linear list of all your slides, with all of your notes on the side. You can double click on the notes to edit the notes directly, or drag the clicks sliders to preview the steps in your slides. --- ## File: guide/animations.md --- outline: deep --- # Animations ## Click Animations > [!NOTE] > Since v0.48.0, we are rewritten the click animations system with much more consistent behaviors. It might change the behaviors of your existing slides in edge cases. While this page is showing the new click system, you can find more details about the refactor in [#1279](https://github.com/slidevjs/slidev/pull/1279). ### `v-click` To apply "click animations" for elements, you can use the `v-click` directive or `` components ```md Hello **World** Hey! ``` ### `v-after` `v-after` is only provided as a directive. It will turn the element visible when the previous `v-click` is triggered. ```md Hello World ``` When you press "next", both `Hello` and `World` will show up together. ### Hide after clicking Add a `.hide` modifier to `v-click` or `v-after` to make the element invisible after clicking, instead of showing up. ```md Visible after 1 click Hidden after 2 click Hidden after 2 click ``` For `v-click` component, you can use the `hide` prop to achieve the same effect: ```md Visible after 1 click Hidden after 2 click ``` ### `v-clicks` `v-clicks` is only provided as a component. It's a shorthand to apply the `v-click` directive to all its child elements. It is especially useful when working with lists and tables. ```md - Item 1 - Item 2 - Item 3 ``` An item will become visible each time you click "next". It accepts a `depth` prop for nested list: ```md - Item 1 - Item 1.1 - Item 1.2 - Item 2 - Item 2.1 - Item 2.2 ``` Also, you can use the `every` prop to specify the number of items to show after each click: ```md - Item 1 (part 1) - Item 1 (part 2) - Item 2 (part 1) - Item 2 (part 2) ``` ### Positioning By default, the clicking animations take place one by one. You can customize the animation position of elements by using the `at` prop or the `v-click` directive with value. Like the CSS layout system, click-animated elements can be "relative" or "absolute": #### Relative Position This actual position of relative elements are calculated based on the previous relative elements: ````md visible after 1 click visible after 3 clicks hidden after 2 clicks ```js {none|1|2}{at:'+5'} 1 // highlighted after 7 clicks 2 // highlighted after 8 clicks ``` ```` > [!NOTE] > The default value of `v-click` is `'+1'` when you don't specify it. In fact, `v-after` are just shortcuts for `v-click` with `at` prop: ```md ``` :::info Only string values start with `'+'` or `'-'` like `'+1'` are treated as relative positions: | Value | Kind | | -------------- | -------- | | `'-1'`, `'+1'` | Relative | | `+1` === `1` | Absolute | | `'1'` | Absolute | So don't forget the single quotes for the relative values. ::: #### Absolute Position The given value is the exact click count to show the element: ````md visible after 3 clicks visible after 2 clicks hidden after 1 click ```js {none|1|2}{at:3} 1 // highlighted after 3 clicks 2 // highlighted after 4 clicks ``` ```` #### Mixed Case You can mix the absolute and relative positions: ```md visible after 1 click visible after 3 clicks visible after 2 click visible after 1 click visible after 4 clicks ``` The following example synchronizes the highlighting of the two code blocks: ````md ```js {1|2}{at:1} 1 + 1 'a' + 'b' ``` ```js {1|2}{at:1} 2 'ab' ``` ```` ### Enter & Leave You can also specify the enter and leave index for the `v-click` directive by passing an array. The end index is exclusive. ```md This will be hidden at click 2 and 3. This will be shown at click 3, and hidden since click 4. ``` You can also use `v-switch` to achieve the same effect: ```md ``` See [`VSwitch` Component](/builtin/components#vswitch) for more details. ### Custom Total Clicks Count By default, Slidev counts how many steps are needed before going to the next slide. You can override this setting by passing the `clicks` frontmatter option: ```yaml --- # 10 clicks in this slide, before going to the next clicks: 10 --- ``` ### Element Transitions When you apply the `v-click` directive to your elements, it will attach the class name `slidev-vclick-target` to it. When the elements are hidden, the class name `slidev-vclick-hidden` will also be attached. For example: ```html Text ``` After a click, it will become ```html Text ``` By default, a subtle opacity transition is applied to those classes: ```css // the default .slidev-vclick-target { transition: opacity 100ms ease; } .slidev-vclick-hidden { opacity: 0; pointer-events: none; } ``` You can override them to customize the transition effects in your custom stylesheets. For example, you can achieve the scaling up transitions by: ```css /* styles.css */ .slidev-vclick-target { transition: all 500ms ease; } .slidev-vclick-hidden { transform: scale(0); } ``` To specify animations for only certain slide or layout ```scss .slidev-page-7, .slidev-layout.my-custom-layout { .slidev-vclick-target { transition: all 500ms ease; } .slidev-vclick-hidden { transform: scale(0); } } ``` Learn more about [customizing styles](/custom/directory-structure#style). ## Rough Markers > Available since v0.48.0 Slidev integrates [Rough Notation](https://github.com/linkstrifer/react-rough-notation) to allow marking or highlighting elements in your slides. ### `v-mark` Rough Notation integrates comes with the `v-mark` directive. #### Type `v-mark.underline` for Underline mark, `v-mark.circle` for Circle mark, etc. Default to `underline` #### Color `v-mark.red` make the notation `red`. Supported builtin color themes from UnoCSS. For custom colors, use object syntax `v-mark="{ color: '#234' }"` #### Clicks `v-mark` works like `v-click` and will trigger after a click. Same as `v-click`, it allows you to pass a custom click value, like `v-mark="5"` or `v-mark="'+1'"`. #### Options Optionally you can pass an object to `v-mark` to specify the options, for example: ```vue Important text ``` #### Preview ## Motion Slidev has [@vueuse/motion](https://motion.vueuse.org/) built-in. You can use the `v-motion` directive to any elements to make apply motion on them. For example ```html Slidev ``` The text `Slidev` will move from `-80px` to its original position on initialization. > Note: Slidev preloads the next slide for performance, which means the animations might start before you navigate to the page. To get it works properly, you can disable the preloading for the particular slide > > ```md > --- > preload: false > --- > ``` > > Or control the element life-cycle with `v-if` to have fine-grained controls > > ```html > v-if="$slidev.nav.currentPage === 7" > v-motion > :initial="{ x: -80 }" > :enter="{ x: 0 }"> > Slidev > > ``` Learn mode: [Demo](https://sli.dev/demo/starter/7) | [@vueuse/motion](https://motion.vueuse.org/) | [v-motion](https://motion.vueuse.org/features/directive-usage) | [Presets](https://motion.vueuse.org/features/presets) ## Slide Transitions > Available since v0.39.0 Slidev supports slide transitions out of the box. You can enable it by setting the `transition` frontmatter option: ```md --- transition: slide-left --- ``` This will give you a nice sliding effects on slide switching. Setting it in the frontmatter will apply to all slides. You can also set different transition per slide. ### Builtin Transitions - `fade` - Crossfade in/out - `fade-out` - Fade out and then fade in - `slide-left` - Slides to the left (slide to right when going backward) - `slide-right` - Slides to the right (slide to left when going backward) - `slide-up` - Slides to the top (slide to bottom when going backward) - `slide-down` - Slides to the bottom (slide to top when going backward) - `view-transition` - Slides with the view transitions API ### View Transitions > Available since v0.43.0 The **View Transitions API** provides a mechanism for easily creating animated transitions between different DOM states. Learn more how it works in [View Transitions API - MDN Web Docs - Mozilla](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API). :::warning Experimental: This is not supported by all browsers. Check the [Browser compatibility table](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#browser_compatibility) carefully before using this. ::: You can use the `view-transition-name` CSS property to name view transitions, which creates connections between different page elements and smooth transitions when switching slides. You can enable [MDC (Markdown Component) Syntax](/guide/syntax#mdc-syntax) support to conveniently name view-transitions: ```md --- transition: view-transition mdc: true --- # View Transition {.inline-block.view-transition-title} --- # View Transition {.inline-block.view-transition-title} ``` ### Custom Transitions Slidev's slide transitions are powered by [Vue Transition](https://vuejs.org/guide/built-ins/transition.html). You can provide your custom transitions by: ```md --- transition: my-transition --- ``` and then in your custom stylesheets: ```css .my-transition-enter-active, .my-transition-leave-active { transition: opacity 0.5s ease; } .my-transition-enter-from, .my-transition-leave-to { opacity: 0; } ``` Learn more how it works in [Vue Transition](https://vuejs.org/guide/built-ins/transition.html). ### Forward & Backward Transitions You can specify different transitions for forward and backward navigation using `|` as a separator in the transition name: ```md --- transition: go-forward | go-backward --- ``` With this, when you go from slide 1 to slide 2, the `go-forward` transition will be applied. When you go from slide 2 to slide 1, the `go-backward` transition will be applied. ### Advanced Usage The `transition` field accepts an option that will passed to the [``](https://vuejs.org/api/built-in-components.html#transition) component. For example: ```md --- transition: name: my-transition enterFromClass: custom-enter-from enterActiveClass: custom-enter-active --- ``` --- ## File: guide/drawing.md # Drawing & Annotations > Available since v0.23 [drauu](https://github.com/antfu/drauu) is built-in for drawing and annotation, should that help improve your presentation further. To start, click the icon in the toolbar and start drawing. It's also available in the [Presenter Mode](/guide/presenter-mode). Drawings and annotations you created will be **synced** automatically across all instances in real time. ## 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. --- ## File: guide/editors.md # Editor Support Since Slidev uses Markdown as the source entry, you can use any editor you prefer to create your slides. If you want some high-level management to your slides, we have provided the following editor integrations for you! ## Integrated Editor Slidev comes with an integrated editor that will instantly reload and save the changes to your file. Click the button to open it. ## VS Code Extension The VS Code extension provides some features to help you better organize your slides and have a quick overview of them. ### Features - Preview slides in the side panel - Slides tree view - Re-ordering slides - Folding for slide blocks - Multiple slides project support - Start the dev server with one click ::: code-group ::: ### Installation You can install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=antfu.slidev). ### Usage Click the `Slidev` icon in the activity bar to open the **Slidev panel**. In the Slidev panel, you can see the projects tree view, slides tree view, and the preview webview. In the **projects tree view**, you can see all the Slidev projects in your workspace. You can dlick the item to open the corresponding file, and click the icon over it to switch the active project. The icon allows you to load a slides project that wasn't scanned automatically. In the **slides tree view**, you can see all the slides in the active project. You can click the item to move you cursor to the slide in the editor, and drag and drop to reorder the slides. In the **preview webview**, you can click the icon to start the dev server and click the icon to open the slides in the browser. Toggle icon to sync/unsync the preview navigation with the editor cursor. There are also some **commands** you can use. Type `Slidev` in the command palette to see them. You can add glob patterns to the `slidev.include` configuration to include files as Slidev entries. The default value is `["**/*.md"]`. Example: ```json { "slidev.include": ["**/presentation.md"] } ``` ## Prettier Plugin Slidev also provides a Prettier plugin to format your slides. You can use it with your favorite editor that supports Prettier. Docs for the plugin can be found [here](https://github.com/slidevjs/prettier-plugin). --- ## File: guide/exporting.md # Exporting ## Slides ### PDF > Exporting to PDF, PPTX, or PNG relies on [Playwright](https://playwright.dev) for rendering. You will therefore need to install [`playwright-chromium`](https://npmjs.com/package/playwright-chromium) to use this feature. > If you are exporting within a CI environment, [the playwright CI guide](https://playwright.dev/docs/ci) can be helpful. 1. Install `playwright-chromium`: ```bash $ npm i -D playwright-chromium ``` 2. Now export your slides to PDF using the following command: ```bash $ slidev export ``` After a few seconds, your slides will be ready at `./slides-export.pdf`. ### 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 ``` ### PPTX (Microsoft PowerPoint) 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, use `--with-clicks false`. ### 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 ``` ### Export Clicks Steps > Available since v0.21 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 ``` ### PDF outline > Available since v0.36.10 You can generate the PDF outline by passing the `--with-toc` option: ```bash $ slidev export --with-toc ``` ### Output filename You can specify the output filename with the `--output` option: ```bash $ slidev export --output my-pdf-export ``` Or in the frontmatter configuration: ```yaml --- exportFilename: my-pdf-export --- ``` ### Export a range of slides 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 entries You can also export multiple slides at once: ```bash $ slidev export slides1.md slides2.md ``` Or ```bash $ slidev export *.md ``` In this case, each input file will generate its own PDF file. ## Presenter notes > Available since v0.36.8 Export only the presenter notes (the last comment block for each slide) into a text document in PDF: ```bash $ slidev export-notes ``` This command also accept multiple entries like for the [export command](#multiple-entries) ## Single-Page Application (SPA) See [Static Hosting](/guide/hosting). ## Exportable Docker Image To support the export feature, there is a [docker image](/guide/install#install-on-docker) (maintained by [@tangramor](https://github.com/tangramor)) with tag **playwright**. Run following command in your work folder: ```bash docker run --name slidev --rm -it \ -v ${PWD}:/slidev \ -p 3030:3030 \ -e NPM_MIRROR="https://registry.npmmirror.com" \ tangramor/slidev:playwright ``` Then you can use the export feature like the following under your work folder: ```bash docker exec -i slidev npx slidev export --timeout 2m --output slides.pdf ``` ## Troubleshooting ### 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: ```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. Don't use this method for testing, rely on web assertions to assess readiness instead. - `'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] ``` --- ## File: guide/faq.md # FAQ ## Grids Since Slidev is based on the Web, you can apply any grid layouts as you want. [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/), you get the full controls. Since [UnoCSS](https://unocss.dev/) is built-in, here's one way that you can reference: ```html The first column The second column ``` Go further, you can customize the size of each column like: ```html The first column (200px) The second column (auto fit) The third column (10% width to parent container) ``` ## Positioning Slides are defined in fixed sizes (default `980x552px`) and scale to fit with the user screen. You can safely use absolute position in your slides as they will scale along with the screen. For example: ```html This is a left-bottom aligned footer ``` To change the canvas' actual size, you can pass the `canvasWidth` options in your first frontmatter: ```yaml --- canvasWidth: 800 --- ``` ## Font Size If you feel the font size in your slides are too small, you can adjust it in a few ways: ### Override Local Style You can override styles for each slide with the inlined ` --- # Page 2 This will not be affected. ``` Learn more: [Embedded Styles](/guide/syntax.html#embedded-styles) ### Override Global Style You can provide custom global styles by creating `./style.css`, for example ```css /* style.css */ h1 { font-size: 10em !important; } ``` Learn more: [Global Style](/custom/directory-structure.html#style) ### Scale the Canvas Changing the canvas' actual size will scale all your contents(text, images, components, etc.) and slides ```yaml --- # default: 980 # since the canvas gets smaller, the visual size will become larger canvasWidth: 800 --- ``` ### Use Transform We provide a built-in component ``, which is a thin wrapper of CSS transform property. ```md - Item 1 - Item 2 ```