## 1. Project Overview & Quickstart (slidevjs/slidev) ## File: README.md ## Features - 📝 [**Markdown-based**](https://sli.dev/guide/syntax) - focus on content and use your favorite editor - 🧑‍💻 [**Developer Friendly**](https://sli.dev/guide/syntax#code-blocks) - built-in code highlighting, live coding, etc. - 🎨 [**Themable**](https://sli.dev/resources/theme-gallery) - theme can be shared and used with npm packages - 🌈 [**Stylish**](https://sli.dev/guide/syntax#embedded-styles) - on-demand utilities via [UnoCSS](https://github.com/unocss/unocss). - 🤹 [**Interactive**](https://sli.dev/custom/directory-structure#components) - embedding Vue components seamlessly - 🎙 [**Presenter Mode**](https://sli.dev/guide/ui#presenter-mode) - use another window, or even your phone to control your slides - 🎨 [**Drawing**](https://sli.dev/features/drawing) - draw and annotate on your slides - 🧮 [**LaTeX**](https://sli.dev/features/latex) - built-in LaTeX math equations support - 📰 [**Diagrams**](https://sli.dev/guide/syntax#diagrams) - creates diagrams using textual descriptions with [Mermaid](https://mermaid.js.org/) - 🌟 [**Icons**](https://sli.dev/features/icons) - access to icons from any icon set directly - 💻 [**Editor**](https://sli.dev/guide/index#editor) - integrated editor, or the [VSCode extension](https://sli.dev/features/vscode-extension) - 🎥 [**Recording**](https://sli.dev/features/recording) - built-in recording and camera view - 📤 [**Portable**](https://sli.dev/guide/exporting) - export into PDF, PNGs, or PPTX - ⚡️ [**Fast**](https://vitejs.dev) - instant reloading powered by [Vite](https://vitejs.dev) - 🛠 [**Hackable**](https://sli.dev/custom/) - using Vite plugins, Vue components, or any npm packages ## Getting Started ### Try it Online ⚡️ [sli.dev/new](https://sli.dev/new) [](https://sli.dev/new) ### Init Project Locally Install [Node.js >= 20.12.0](https://nodejs.org/) and run the following command: ```bash npm init slidev ``` Documentation: **[English](https://sli.dev)** | [中文文档](https://cn.sli.dev) | [Français](https://fr.sli.dev) | [Español](https://es.sli.dev) | [Русский](https://ru.sli.dev) | [Português-BR](https://br.sli.dev) Discord: [chat.sli.dev](https://chat.sli.dev) For a full example, you can check the [demo](https://github.com/slidevjs/slidev/blob/main/demo) folder, which is also the source file for [my previous talk](https://antfu.me/posts/composable-vue-vueday-2021). ## Tech Stack - [Vite](https://vitejs.dev) - An extremely fast frontend tooling - [Vue 3](https://v3.vuejs.org/) powered [Markdown](https://daringfireball.net/projects/markdown/syntax) - Focus on the content while having the power of HTML and Vue components whenever needed - [UnoCSS](https://github.com/unocss/unocss) - On-demand utility-first CSS engine, style your slides at ease - [Shiki](https://github.com/shikijs/shiki), [Monaco Editor](https://github.com/Microsoft/monaco-editor) - First-class code snippets support with live coding capability - [RecordRTC](https://recordrtc.org) - Built-in recording and camera view - [VueUse](https://vueuse.org) family - [`@vueuse/core`](https://github.com/vueuse/vueuse), [`@vueuse/motion`](https://github.com/vueuse/motion), etc. - [Iconify](https://iconify.design/) - Icon sets collection. - [Drauu](https://github.com/antfu/drauu) - Drawing and annotations support - [KaTeX](https://katex.org/) - LaTeX math rendering. - [Mermaid](https://mermaid-js.github.io/mermaid) - Textual Diagrams. ## Sponsors This project is made possible by all the sponsors supporting my work: ## License MIT License © 2021 [Anthony Fu](https://github.com/antfu) --- ## File: demo/starter/README.md See [../../packages/create-app/template/README.md](../../packages/create-app/template/README.md) --- ## File: demo/README.md The best way of understanding Slidev is to try it, with the following command: ```bash npm init slidev ``` Learn more: https://sli.dev --- ## File: docs/builtin/cli.md # Slidev CLI `@slidev/cli` exposes a binary called `slidev` that you can use to develop, build, and export your slides. ## Prerequisites To use the CLI, you can either install `@slidev/cli` globally or install it locally in your Node.js project. If you created your project with `npm init slidev`, the CLI is already installed locally. ::: warning Usually `npx slidev` is not supported because the package name is actually `@slidev/cli`. ::: The CLI options of the commands obey the following conventions: - the value of the option can be passed after a space or a `=` character: Example: `slidev --port 8080` is equivalent to `slidev --port=8080` - `true` can be omitted for boolean options: Example: `slidev --open` is equivalent to `slidev --open true` ::: info If you use npm, please don't forget to add `--` before the options to pass them to Slidev: ```bash npm run slidev -- --remote --port 8080 --open ``` ::: ## `slidev [entry]` {#dev} Start a local server for Slidev. - `[entry]` (`string`, default: `slides.md`): path to the markdown file containing your slides. Options: - `--port`, `-p` (`number`, default: `3030`): port number. - `--base` (`string`, default: `/`): base URL (see https://vitejs.dev/config/shared-options.html#base). - `--open`, `-o` (`boolean`, default: `false`): open in the browser. - `--remote [password]` (`string`): listen to the public host and enable remote control, if a value is passed then the presenter mode is private and only accessible by passing the given password in the URL query `password` parameter. - `--bind` (`string`, default: `0.0.0.0`): specify which IP addresses the server should listen on in the remote mode. - `--log` (`'error', 'warn', 'info', 'silent'`, default: `'warn'`): Log level. - `--force`, `-f` (`boolean`, default: `false`): force the optimizer to ignore the cache and re-bundle. - `--theme`, `-t` (`string`): override theme. ## `slidev build [entry]` {#build} Build a hostable SPA. See for more details. - `[entry]` (`string`, default: `slides.md`): path to the slides markdown file. Options: - `--out`, `-o` (`string`, default: `dist`): output directory - `--base` (`string`, default: `/`): base URL (see https://vitejs.dev/config/shared-options.html#base) - `--download` (`boolean`, default: `false`): allow the download of the slides as a PDF inside the SPA - `--theme`, `-t` (`string`): override theme - `--without-notes` (`boolean`, default: `false`): exclude speaker notes from the SPA ## `slidev export [...entry]` {#export} Export slides to PDF (or other format). See for more details. - `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry. Options: - `--output` (`string`, default: use `exportFilename` (see https://sli.dev/custom/#frontmatter-configures) or use `[entry]-export`): path to the output. - `--format` (`'pdf', 'png', 'pptx', 'md'`, default: `'pdf'`): output format. - `--timeout` (`number`, default: `30000`): timeout for rendering the print page (see https://playwright.dev/docs/api/class-page#page-goto). - `--range` (`string`): page ranges to export (example: `'1,4-5,6'`). - `--dark` (`boolean`, default: `false`): export as dark theme. - `--with-clicks`, `-c` (`boolean`, default: `false`): export pages for every click animation (see https://sli.dev/guide/animations.html#click-animation). - `--theme`, `-t` (`string`): override theme. - `--omit-background` (`boolean`, default: `false`): remove the default browser background ## `slidev format [entry]` {#format} Format the markdown file. Note that this won't format the content of the slides, only the organization of the markdown file. - `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry. ## `slidev mcp [entry]` {#mcp} Start an MCP (Model Context Protocol) server over stdio for AI agents to inspect and edit the slides. See . - `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry. ## `slidev theme [subcommand]` {#theme} Theme-related operations. Subcommands: - `eject [entry]`: Eject the current theme into the local file system. See . - `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry. - Options: - `--dir` (`string`, default: `theme`): the output dir. - `--theme`, `-t` (`string`): override theme. --- ## File: docs/builtin/components.md # Components This page lists all the built-in components provided by Slidev. These components can be **directly** used in your slides. Note that can provide additional components. To add your own components, see . ## `Arrow` Draw an arrow. ### Usage ```md ``` Or: ```md ``` Props: - `x1` (`string | number`, required): start point x position - `y1` (`string | number`, required): start point y position - `x2` (`string | number`, required): end point x position - `y2` (`string | number`, required): end point y position - `width` (`string | number`, default: `2`): line width - `color` (`string`, default: `'currentColor'`): line color - `two-way` (`boolean`, default: `false`): draw a two-way arrow ## `VDragArrow` An `Arrow` component that can be dragged. ### Usage Props not related to position are the same as [the `Arrow` component](#arrow). ## `AutoFitText` Box inside which the font size will automatically adapt to fit the content, powered by [fitty](https://github.com/rikschennink/fitty). Similar to PowerPoint or Keynote TextBox. ### Usage ```md ``` Props: - `max` (`number`, default `100`): Maximum font size in pixels - `min` (`number`, default `30`): Minimum font size in pixels - `modelValue` (`string`, default `''`): Text content (alternatively, use the default slot) - `multiLine` (`boolean`, default `true`): Allow the text to wrap when the minimum font size is reached ## `LightOrDark` Use it to display one thing or another depending on the active light or dark theme. ### Usage Use it with the two named Slots `#dark` and `#light`: ```md ``` Provided props on `LightOrDark` component will be available using scoped slot props: ```md ``` You can provide markdown in the slots, but you will need to surround the content with blank lines: ```md ``` ## `Link` Insert a link you can use to navigate to a given slide. ### Usage ```md Go to slide 42 ``` Props: - `to` (`string | number`): The path of the slide to navigate to (slides path starts from `1`) - `title` (`string`): The title to display One can use a string as `to`, provided the corresponding route exists, e.g. ```md --- routeAlias: solutions --- # Now some solutions! ``` ## `PoweredBySlidev` Renders "Powered by Slidev" with a link to the Slidev website. ## `RenderWhen` Render slots depend on whether the context matches (for example whether we are in presenter view). ### Usage ```md This will only be rendered in presenter view. ``` Context type: `'main' | 'visible' | 'print' | 'slide' | 'overview' | 'presenter' | 'previewNext'` Props: - `context` (`Context | Context[]`): a context or array of contexts you want to check for - `'main'`: Render in slides and presenter view (equivalent to ['slide', 'presenter']), - `'visible'`: Render the content if it is visible - `'print'`: Render in print mode - `'slide'`: Render in slides - `'overview'`: Render in overview - `'presenter'`: Render in presenter view - `'previewNext'`: Render in presenter's next slide view Slots: - `#default`: Rendered when the context matches - `#fallback`: Rendered when the context does not match ## `SlideCurrentNo` Current slide number. ### Usage ```md ``` ## `SlidesTotal` Total number of slides. ### Usage ```md ``` ## `TitleRenderer` Insert the main title from a slide parsed as HTML. Titles and title levels get automatically retrieved from the first title element of each slide. You can override this automatic behavior for a slide by using the front matter syntax: ```yml --- title: Amazing slide title level: 2 --- ``` ### Usage The `` component is a virtual component you can import with: ```js import TitleRenderer from '#slidev/title-renderer' ``` Then you can use it with: ```md ``` Props: - `no` (`string | number`): The number of the slide to display the title from (slides starts from `1`) ## `Toc` Insert a Table Of Content. If you want a slide to not appear in the `` component, you can use the `hideInToc` option in the frontmatter of the slide: ```yml --- hideInToc: true --- ``` Titles are displayed using the [`` component](#titles) ### Usage ```md ``` Props: - `columns` (`string | number`, default: `1`): The number of columns of the display - `listClass` (`string | string[]`, default: `''`): Classes to apply to the table of contents list - `maxDepth` (`string | number`, default: `Infinity`): The maximum depth level of title to display - `minDepth` (`string | number`, default: `1`): The minimum depth level of title to display - `mode` (`'all' | 'onlyCurrentTree'| 'onlySiblings'`, default: `'all'`): - `'all'`: Display all items - `'onlyCurrentTree'`: Display only items that are in current tree (active item, parents and children of active item) - `'onlySiblings'`: Display only items that are in current tree and their direct siblings ## `Transform` Apply scaling or transforming to elements. ### Usage ```md ``` Props: - `scale` (`number | string`, default `1`): transform scale value - `origin` (`string`, default `'top left'`): transform origin value ## `Tweet` Embed a tweet. ### Usage ```md ``` Props: - `id` (`number | string`, required): id of the tweet - `scale` (`number | string`, default `1`): transform scale value - `conversation` (`string`, default `'none'`): [tweet embed parameter](https://developer.twitter.com/en/docs/twitter-for-websites/embedded-tweets/guides/embedded-tweet-parameter-reference) - `cards` (`'hidden' | 'visible'`, default `'visible'`): [tweet embed parameter](https://developer.twitter.com/en/docs/twitter-for-websites/embedded-tweets/guides/embedded-tweet-parameter-reference) ## `BlueSky` Embed a Bluesky post. ### Usage ```md ``` Props: - `uri` (`string`, required): AT-URI of the Bluesky post, or a `https://bsky.app/profile/.../post/...` URL - `scale` (`number | string`, default `1`): transform scale value ## `VAfter`, `VClick` and `VClicks` ## `VSwitch` Switch between multiple slots based on clicks. - If the `unmount` prop is set to `true`, the previous slot will be unmounted when switching to the next slot. Default is `false`. - Use the `tag` and `childTag` props to change the default tag of the component and its children. Default is `div`. - Use the `transition` prop to change the transition effect. Default is `false` (disabled). ## `VDrag` ## `SlidevVideo` Embed a video. ### Usage ```md Your browser does not support videos. You may download it [here](/myMovie.mp4). ``` Check [HTML video element's doc](https://developer.mozilla.org/docs/Web/HTML/Element/Video) to see what can be included in this component's slot. Props: - `controls` (`boolean`, default: `false`): show the video controls - `autoplay` (`boolean | 'once'`, default: `false`): - `true` or `'once'`: start the video only once and does not restart it once ended or paused - `false`: never automatically start the video (rely on `controls` instead) - `autoreset` (`'slide' | 'click'`, default: `undefined`): - `'slide'`: go back to the start of the video when going back to the slide - `'click'`: go back to the start of the video when going back to the component's click turn - `poster` (`string | undefined`, default: `undefined`): - The source of the image to print when the video is not playing. - `printPoster` (`string | undefined`, default: `undefined`): - The override for `poster` when printing. - `timestamp` (`string | number`, default: `0`): - The starting time of the video in seconds. - `printTimestamp` (`string | number | 'last' | undefined`, default: `undefined`): - The override for `timestamp` when printing. ::: warning When exporting, the video may fail to load because Chromium does not support some video formats. In this case, you can specify the executable path of the browser. See [Chromium executable path](/guide/exporting.html#executable-path) for more information. ::: ## `Youtube` Embed a YouTube video. ### Usage ```md ``` Props: - `id` (`string`, required): id of the YouTube video - `width` (`number`): width of the video - `height` (`number`): height of the video You can also make the video start at a specific time if you add `?start=1234` to the id value (where `1234` is seconds), --- ## File: docs/builtin/layouts.md # Layouts This page lists all the built-in layouts provided by Slidev. These layouts can be used via the `layout` option in the frontmatters of your slides. Note that may provide additional layouts or override the existing ones. To add your own layouts, see . ## `center` Displays the content in the middle of the screen. ## `cover` Used to display the cover page for the presentation, may contain the presentation title, contextualization, etc. ## `default` The most basic layout, to display any kind of content. ## `end` The final page for the presentation. ## `fact` To show some fact or data with a lot of prominence on the screen. ## `full` Use all the space of the screen to display the content. ## `image-left` Shows an image on the left side of the screen, the content will be placed on the right side. ### Usage ```yaml --- layout: image-left # the image source image: /path/to/the/image # a custom class name to the content class: my-cool-content-on-the-right --- ``` ## `image-right` Shows an image on the right side of the screen, the content will be placed on the left side. ### Usage ```yaml --- layout: image-right # the image source image: /path/to/the/image # a custom class name to the content class: my-cool-content-on-the-left --- ``` ## `image` Shows an image as the main content of the page. ### Usage ```yaml --- layout: image # the image source image: /path/to/the/image --- ``` You can change the default background size (`cover`) by adding the `backgroundSize` attribute: ```yaml --- layout: image image: /path/to/the/image backgroundSize: contain --- ``` ```yaml --- layout: image-left image: /path/to/the/image backgroundSize: 20em 70% --- ``` ## `iframe-left` Shows a web page on the left side of the screen, the content will be placed on the right side. ### Usage ```yaml --- layout: iframe-left # the web page source url: https://github.com/slidevjs/slidev # a custom class name to the content class: my-cool-content-on-the-right --- ``` ## `iframe-right` Shows a web page on the right side of the screen, the content will be placed on the left side. ### Usage ```yaml --- layout: iframe-right # the web page source url: https://github.com/slidevjs/slidev # a custom class name to the content class: my-cool-content-on-the-left --- ``` ## `iframe` Shows a web page as the main content of the page. ### Usage ```yaml --- layout: iframe # the web page source url: https://github.com/slidevjs/slidev --- ``` ## `intro` To introduce the presentation, usually with the presentation title, a short description, the author, etc. ## `none` A layout without any existing styling. ## `quote` To display a quotation with prominence. ## `section` Used to mark the beginning of a new presentation section. ## `statement` Make an affirmation/statement as the main page content. ## `two-cols` Separates the page content in two columns. ### Usage ```md --- layout: two-cols --- # Left This shows on the left ::right:: # Right This shows on the right ``` ## `two-cols-header` Separates the upper and lower lines of the page content, and the second line separates the left and right columns. ### Usage ```md --- layout: two-cols-header --- This spans both ::left:: # Left This shows on the left ::right:: # Right This shows on the right ``` --- ## File: docs/custom/config-code-runners.md # Configure Code Runners Define code runners for custom languages in your Monaco Editor. By default, JavaScript, TypeScript runners are supported built-in. They run in the browser **without** a sandbox environment. If you want more advanced integrations, you can provide your own code runner that sends the code to a remote server, runs in a Web Worker, or anything, up to you. Create `./setup/code-runners.ts` with the following content: ```ts twoslash [setup/code-runners.ts] /* eslint-disable import/first */ declare const executePythonCodeRemotely: (code: string) => Promise declare const sanitizeHtml: (html: string) => string // ---cut--- import { defineCodeRunnersSetup } from '@slidev/types' export default defineCodeRunnersSetup(() => { return { async python(code, ctx) { // Somehow execute the code and return the result const result = await executePythonCodeRemotely(code) return { text: result } }, html(code, ctx) { return { html: sanitizeHtml(code) } }, // or other languages, key is the language id } }) ``` ## Runner Context The second argument `ctx` is the runner context, which contains the following properties: ```ts twoslash import type { CodeRunnerOutputs } from '@slidev/types' import type { CodeToHastOptions } from 'shiki' // ---cut--- export interface CodeRunnerContext { /** * Options passed to runner via the `runnerOptions` prop. */ options: Record /** * Highlight code with shiki. */ highlight: (code: string, lang: string, options?: Partial) => string /** * Use (other) code runner to run code. */ run: (code: string, lang: string) => Promise } ``` ## Runner Output The runner can either return a text or HTML output, or an element to be mounted. Refer to https://github.com/slidevjs/slidev/blob/main/packages/types/src/code-runner.ts for more details. ## Additional Runner Dependencies By default, Slidev will scan the Markdown source and automatically import the necessary dependencies for the code runners. If you want to manually import dependencies, you can use the `monacoRunAdditionalDeps` option in the [headmatter](./index#headmatter): ```yaml monacoRunAdditionalDeps: - ./path/to/dependency - lodash-es ``` ::: tip The paths are resolved relative to the `snippets` directory. And the names of the deps should be exactly the same as the imported ones in the code. ::: --- ## 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 twoslash [./setup/context-menu.ts] // ---cut--- import { useNav } from '@slidev/client' import { defineContextMenuSetup } from '@slidev/types' import { computed } from 'vue' // ---cut-start--- // @ts-expect-error missing types // ---cut-end--- import Icon3DCursor from '~icons/carbon/3d-cursor' export default defineContextMenuSetup((items) => { const { isPresenter } = useNav() return computed(() => [ ...items.value, { small: false, icon: Icon3DCursor, // if `small` is `true`, only the icon is shown 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-fonts.md # Configure Fonts While you can use HTML and CSS to customize the fonts and style for your slides as you want, Slidev also provides a convenient way to use them effortlessly. In your frontmatter, configure as the following: ```yaml --- fonts: # basically the text sans: Robot # use with `font-serif` css class from UnoCSS serif: Robot Slab # for code blocks, inline code, etc. mono: Fira Code --- ``` And that's all. Fonts will be **imported automatically from a provider via CDN, by default it is [Google Fonts](https://fonts.google.com/)**. That means you can use any fonts available on Google Fonts directly. ## Local Fonts By default, Slidev assumes all the fonts specified via `fonts` configurations come from Google Fonts. If you want to use local fonts, specify the `fonts.local` to opt-out the auto-importing. ```yaml --- fonts: # like font-family in css, you can use `,` to separate multiple fonts for fallback sans: 'Helvetica Neue,Robot' # mark 'Helvetica Neue' as local font local: Helvetica Neue --- ``` ## Weights & Italic By default, Slidev imports three weights `200`,`400`,`600` for each font. You can configure them by: ```yaml --- fonts: sans: Robot # default weights: '200,400,600' # import italic fonts, default `false` italic: false --- ``` This configuration applies to all web fonts. For more fine-grained controls of each font's weights, you will need to manually import them with [HTML](/custom/directory-structure.html#index-html) and CSS. ## Fallback Fonts For most of the scenarios, you only need to specify the "special font" and Slidev will append the fallback fonts for you, for example: ```yaml --- fonts: sans: Robot serif: Robot Slab mono: Fira Code --- ``` will result in ```css .font-sans { font-family: "Robot",ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"; } .font-serif { font-family: "Robot Slab",ui-serif,Georgia,Cambria,"Times New Roman",Times,serif; } .font-mono { font-family: "Fira Code",ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace; } ``` If you want to disable the fallback fonts, configure as the following: ```yaml --- fonts: mono: 'Fira Code, monospace' fallbacks: false --- ``` ## Providers - Options: `google` | `coollabs` | `none` - Default: `google` Currently, only [Google Fonts](https://fonts.google.com/) and [coolLabs](https://fonts.coollabs.io/) supported, we are planning to add more providers in the future. Specify to `none` will disable the auto-importing feature entirely and treat all the fonts locally. ```yaml --- fonts: provider: none --- ``` --- ## File: docs/custom/config-highlighter.md # Configure Highlighter Slidev uses [Shiki](https://github.com/shikijs/shiki) as the code highlighter. It's a TextMate Grammar powered syntax highlighter as accurate as VS Code. It generates colored tokens so no additinal CSS is required. Shiki also comes with [a bunch of built-in themes](https://shiki.style/themes). In Slidev, we also provided the [TwoSlash](#twoslash-integration) support. ## Configure Shiki Create `./setup/shiki.ts` file with the following content: ```ts twoslash [setup/shiki.ts] import { defineShikiSetup } from '@slidev/types' export default defineShikiSetup(() => { return { themes: { dark: 'min-dark', light: 'min-light', }, transformers: [ // ... ], } }) ``` If you want to add custom theme or language (TextMate grammar/themes in JSON), you can import them in the setup file: ```ts twoslash [setup/shiki.ts] import { defineShikiSetup } from '@slidev/types' // ---cut-start--- // @ts-expect-error missing types // ---cut-end--- import customLanguage from './customLanguage.tmLanguage.json' // ---cut-start--- // @ts-expect-error missing types // ---cut-end--- import customTheme from './customTheme.tmTheme.json' export default defineShikiSetup(() => { return { themes: { dark: customTheme, light: 'min-light', }, langs: [ 'js', 'typescript', 'cpp', customLanguage, // ... ], transformers: [ // ... ], } }) ``` Check [Built-in languages](https://shiki.style/languages) and [Built-in themes](https://shiki.style/themes), and refer to [Shiki's docs](https://shiki.style) for more details. :::info For now, Shiki Magic Move does not support transformers. ::: ## Configure Prism :::warning Prism support has been removed since v0.50. Please use Shiki instead. ::: ## 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 ```