Slidev User Guide

Slidev (slide + dev) is a slides maker and presenter for developers. You write your presentation as a single Markdown file, and Slidev turns it into an interactive, themeable, web-based slide deck — complete with syntax-highlighted code, live code editors, diagrams, math, animations, a presenter mode, and one-command export to PDF, PNG, PPTX, or a hostable website.

This guide is for the people who make and give presentations with Slidev. It covers installing the tool, writing slides in Markdown, every feature you can use on a slide, presenting live, and exporting or publishing the result. Architecture, configuration internals, and deployment operations live in the companion Slidev Admin Guide.

Note

Slidev is built on standard web technology — Vue 3, Vite, and Markdown. You do not need to know Vue to use it, but anything you can do on a web page, you can do on a slide.

1. Quick Start

The fastest way to start a new presentation is the project scaffolder. You need Node.js 20.12.0 or newer.

npm

npm init slidev@latest

pnpm

pnpm create slidev

yarn

yarn create slidev

The scaffolder creates a project folder, installs dependencies, writes a starter slides.md, and offers to start the dev server. Once running you will see:

  ●■▲
  Slidev  v52.16.0

  public slide show   > http://localhost:3030/
  presenter mode      > http://localhost:3030/presenter/
  slides overview     > http://localhost:3030/overview/
  export slides       > http://localhost:3030/export/

  shortcuts           > restart | open | edit | quit

Open http://localhost:3030 in your browser. Edit slides.md in your editor — the deck reloads instantly as you type.

Tip

Every slide is separated by a line containing exactly ---. Start writing immediately: type a heading, add ---, and you have two slides.

A minimal slides.md:

---
theme: default
title: My First Deck
---

# Welcome to Slidev

A presentation written in Markdown.

---

## Second Slide

- Bullet one
- Bullet two

2. Installation

2.1 Scaffold a new project (recommended)

npm init slidev@latest (above) is the recommended path for a new deck. It produces a ready-to-run project with @slidev/cli and a theme already wired up.

2.2 Add Slidev to an existing project

Install the CLI and a theme as dev dependencies, then add scripts:

npm install -D @slidev/cli @slidev/theme-default

{
  "scripts": {
    "dev": "slidev",
    "build": "slidev build",
    "export": "slidev export"
  }
}

Create a slides.md and run npm run dev.

2.3 Run without installing

You can invoke Slidev directly with npx against a Markdown file:

npx @slidev/cli slides.md

Note

If the entry file you point at does not exist, Slidev offers to create it from a built-in template (when run in an interactive terminal). In a non-interactive environment (CI, scripts), a missing entry file is a hard error instead.

2.4 Optional: PDF/PNG/PPTX export support

Exporting to PDF, PNG, or PPTX renders slides through a real browser using Playwright. Install the browser engine when you need export:

npm install -D playwright-chromium

You only need this for the export command — it is not required for authoring or for the hostable website build. See §8 Exporting.

Important

Requirements at a glance: Node.js ≥ 20.12.0, a modern browser to view the deck, and (for export only) playwright-chromium. Slidev itself is installed per-project; a global install is also supported.

3. Writing Slides

A Slidev deck is one Markdown file (by default slides.md). This section covers the syntax you use to turn Markdown into slides.

3.1 Separating slides

Slides are divided by a horizontal rule — a line containing only ---:

# Slide 1

Content of the first slide.

---

# Slide 2

Content of the second slide.

Caution

A --- that immediately follows content with a non-empty line after it is treated as frontmatter for the next slide, not a separator (see §3.2). Slidev's parser also ignores --- that appears inside fenced code blocks and HTML comments, so you can safely show --- in a code sample.

3.2 Slide frontmatter

Each slide can carry a YAML frontmatter block that configures that slide. The first slide's frontmatter is special: it is the headmatter and configures the whole deck (see §11 Configuring the Deck and the Admin Guide).

---
layout: center
class: text-center
transition: slide-left
---

# A Centered Title Slide

Slidev supports two frontmatter styles. The standard --- fenced block above, and a YAML code-block style that keeps your Markdown valid in other tools:

---

```yaml
layout: image-right
image: /photo.png
```

# Slide with a photo on the right

Per-slide frontmatter keys you will use most often:

Tip

Use the format command to tidy frontmatter and slide content automatically: slidev format slides.md. It re-serializes every slide through Slidev's parser.

3.3 Layouts

A layout wraps your slide content in a predefined arrangement. Set it with the layout frontmatter key. Slidev ships these built-in layouts:

Two-column example:

---
layout: two-cols
---

# Left column

Content on the left.

::right::

# Right column

Content on the right.

Note

Themes and addons can add their own layouts, and you can define custom ones in a layouts/ folder in your project. See the Admin Guide for authoring layouts.

3.4 Code blocks

Code is a first-class citizen. Standard fenced code blocks are highlighted with Shiki (the same engine VS Code uses), so colors match your editor exactly.

```ts
function greet(name: string) {
  return `Hello, ${name}`
}
```

Line highlighting. Add line numbers in braces after the language; use | to step through highlights across clicks:

```ts {2,3}
function add(a: number, b: number) {
  const sum = a + b
  return sum
}
```

```ts {1|2|3}
const a = 1   // highlighted on click 1
const b = 2   // highlighted on click 2
const c = 3   // highlighted on click 3
```

Line numbers. Show them per-block with {lines:true}, or globally with the lineNumbers headmatter option (default off).

TwoSlash. TypeScript code can show inline type information and hover tooltips with TwoSlash. It is enabled by default (twoslash: true):

```ts twoslash
const greeting = 'hello'
//    ^?
```

Magic Move. Animate a code block transforming between steps by wrapping multiple blocks in `````md magic-move`:

````md magic-move
```ts
const count = 1
```
```ts
const count = ref(1)
```
````

A copy button appears on code blocks by default (codeCopy: true), and on Magic Move steps (magicMoveCopy: true).

Tip

Magic Move's transition speed is controlled by magicMoveDuration (default 800 ms).

3.5 Editable and runnable code (Monaco)

Turn any code block into a live, editable Monaco editor by adding {monaco}:

```ts {monaco}
const numbers = [1, 2, 3]
console.log(numbers.map(n => n * 2))
```

Make it runnable with {monaco-run} — your audience can edit and execute the code live during the talk:

```ts {monaco-run}
console.log('This runs in the slide!')
```

Monaco is enabled by default (monaco: true) and only loaded on slides that use it.

Note

Monaco type intelligence is loaded from your local node_modules by default (monacoTypesSource: local). You can switch it to fetch types from a CDN — see the Admin Guide's configuration reference.

3.6 Diagrams and math

Mermaid diagrams render from a mermaid code block:

```mermaid
graph LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Do it]
  B -->|No| D[Skip]
```

LaTeX math via KaTeX. Inline with single $, block with $$:

Inline: $E = mc^2$

$$
\int_0^\infty e^{-x}\,dx = 1
$$

PlantUML diagrams are rendered through a PlantUML server (default https://www.plantuml.com/plantuml) using a plantuml code block.

Note

Slidev auto-detects which of these features a deck uses (math, Monaco, Mermaid, and tweet/Bluesky embeds) and only loads the corresponding machinery — so a deck without math never pays for KaTeX.

3.7 Click animations

Reveal content step-by-step as you click. Use the built-in v-click and v-clicks directives/components:

<v-click>

This appears on the first click.

</v-click>

<v-clicks>

- These list items
- appear one
- per click

</v-clicks>

• v-click — reveal an element on a click.
• v-clicks — reveal each child (e.g. list items) one click at a time.
• v-after — appear together with the previous v-click.
• v-click="3" — appear at a specific click number; ranges like [2, 5] show the element only between clicks 2 and 5.

You normally do not need to count clicks — Slidev calculates the total from the directives on the slide. Override it with the clicks frontmatter key when needed, or start animations later with clicksStart.

3.8 Speaker notes

Anything in an HTML comment at the end of a slide becomes that slide's speaker notes, visible in presenter mode (§7.2) and exportable (§8.4):

# My Slide

Visible content.

<!--
These are my private speaker notes.
They show up in presenter mode and notes export.
-->

Tip

For Japanese (and other) furigana in notes, the notesAutoRuby option auto-wraps configured words in <ruby> tags. See the Admin Guide configuration reference.

3.9 Importing slides from other files

Split a large deck across files and pull them in with the src frontmatter key. You can import a whole file or a slide range with #:

---
src: ./chapters/intro.md
---

---
src: ./chapters/deep-dive.md#2-5
---

Ranges use the same syntax as export ranges: 1,3-5,8, all/* for everything, or none. Frontmatter you place alongside src: is passed down as an override to the imported slides.

Warning

If an imported file is missing, Slidev reports Imported markdown file not found: with the resolved path and continues with the other slides. Double-check relative paths — /-prefixed paths resolve from your project root, others from the importing file's directory.

3.10 Images, media, and components

• Images: standard Markdown ![alt](/image.png) (public assets live in public/), or styled with HTML/Vue for sizing and positioning.
• Backgrounds: set a slide background with the background: frontmatter key, or use the image/cover layouts.
• Vue components: Slidev ships built-in components you can drop into any slide, such as <Toc> (table of contents), <Link> (navigate to another slide), <Tweet>, <Youtube>, and <Arrow>. Because slides are Vue under the hood, you can also write your own components in a components/ folder and use them directly.

Note

The full catalog of built-in components and their props is maintained on the official site at sli.dev. This guide focuses on the Markdown authoring you do day to day; the Admin Guide covers adding custom components and layouts.

4. Styling and Fonts

Slidev styles slides with UnoCSS, so you can use utility classes directly in your Markdown and in the class: frontmatter:

---
class: text-center text-blue-500
---

# A centered, blue title

Configure fonts entirely from the headmatter — Slidev fetches the web fonts for you (default provider: Google Fonts):

---
fonts:
  sans: Roboto
  serif: Roboto Slab
  mono: Fira Code
---

Sensible system-font fallbacks are appended automatically unless you disable fonts.fallbacks. To use only locally-installed fonts, list them under fonts.local.

5. Themes and Addons

A theme controls the look of your deck; an addon adds reusable slides, components, or behavior.

Use a theme by setting the theme headmatter key on the first slide:

---
theme: seriph
---

Theme names resolve in this order:

• theme: seriph → the official @slidev/theme-seriph package.
• theme: slidev-theme-name → a community theme (the slidev-theme- prefix convention).
• theme: ./my-theme or an absolute path → a local theme folder.
• theme: none → no theme.

If the named theme is not installed, Slidev offers to install it for you (in an interactive terminal). Addons are listed under the addons headmatter array.

Tip

To customize an installed theme, eject it into your project and edit it directly:

slidev theme eject

This copies the theme into a local theme/ folder and rewrites your deck's theme: key to point at it.

6. Navigating and Animating

6.1 Keyboard and on-screen navigation

While presenting in the browser you can move with the arrow keys, click the on-screen controls, or open the slides overview to jump anywhere. The dev server prints the overview URL (/overview/) on startup.

6.2 Dev-server shortcuts (terminal)

While slidev is running, these single-key shortcuts work in the terminal:

6.3 The navigation bar API

Slidev exposes navigation actions (next/previous, jump to first/last, go to a slide, toggle dark mode, toggle the overview, toggle drawing, download the PDF, open the go-to dialog). These power the on-screen controls and presenter mode, and are available to custom components via the useNav() composable documented on sli.dev.

6.4 Slide transitions

Set a transition with the transition headmatter (for the whole deck) or per-slide frontmatter. Built-in transitions:

fade, fade-out, slide-up, slide-down, slide-left, slide-right, view-transition.

---
transition: slide-left
---

7. Presenting Live

7.1 The dev server

slidev (or npm run dev) starts the presentation server. Useful flags:

slidev --open          # open the browser automatically
slidev --port 4000     # choose a port (auto-picks 3030–4000 otherwise)
slidev slides2.md      # present a different entry file

7.2 Presenter mode

Open the /presenter/ URL (printed on startup). Presenter mode shows the current slide, a preview of the next slide, your speaker notes, and a timer. Navigation in presenter mode stays in sync with the public view.

The presentation timer can be a stopwatch (default) or a countdown toward the slide's expected duration (default 30min) — both configurable in the headmatter.

7.3 Drawing and annotations

Slidev includes a drawing tool (powered by Drauu) so you can annotate slides live. It is enabled by default; drawings can optionally be restricted to presenter mode, persisted to disk, and synchronized across connected viewers. See the Admin Guide's drawings config.

7.4 Recording

A built-in camera/recording feature (RecordRTC) lets you record yourself alongside the slides. It is available in dev by default (record: 'dev').

7.5 Remote control over the network

Expose the server to your local network (and optionally the internet) so you can drive the deck from your phone:

slidev --remote                 # listen on your LAN
slidev --remote yourpassword    # require a password for presenter mode
slidev --remote --tunnel        # also open a Cloudflare Quick Tunnel (public URL)

When --remote is on, the startup banner prints LAN URLs and your public IP; press c in the terminal for a scannable QR code.

Caution

--remote makes your presenter mode reachable on the network. Always pass a password (--remote <password>) when presenting on an untrusted network, and remember that --tunnel publishes a public URL to the internet for the duration of the session.

8. Exporting Your Deck

Export renders your slides through a headless browser, so install playwright-chromium first (§2.4).

8.1 PDF (default)

slidev export

This produces a PDF next to your slides. Control the output and content:

slidev export --output talk.pdf
slidev export --range 1,4-6        # only some slides
slidev export --dark               # force dark theme
slidev export --with-clicks        # one page per click step
slidev export --with-toc           # add a clickable PDF outline

8.2 PNG, PPTX, and Markdown

Choose the format with --format:

slidev export --format png         # one image per slide
slidev export --format pptx        # PowerPoint (images + speaker notes)
slidev export --format md          # Markdown with image references

PPTX export embeds each slide as an image and carries your speaker notes into the PowerPoint notes pane; it captures click steps automatically.

8.3 Export options reference

8.4 Exporting speaker notes

slidev export-notes --output notes.pdf

This renders your speaker notes (from the presenter print view) to their own PDF.

8.5 Exporting from the browser

Slidev also offers an in-browser exporter — start the dev server and visit the /export/ URL printed at startup. The CLI reminds you of this the first time you run slidev export.

Tip

Slidev embeds metadata into exported PDFs from your first slide's frontmatter: title, author, info, and keywords. Fill those in to get a properly-tagged PDF.

9. Building and Publishing a Website

Turn your deck into a static, hostable single-page app:

slidev build

The result lands in dist/ and can be served by any static host. Common options:

slidev build --out public          # change the output directory
slidev build --base /talk/         # deploy under a sub-path
slidev build --download            # include a downloadable PDF + a download button
slidev build --without-notes       # strip speaker notes from the public build

For deploying under a sub-path (e.g. GitHub Pages project sites), use hash-based routing so deep links work without server rewrites:

slidev build --base /my-talk/ --router-mode hash

The build automatically writes a 404.html (so GitHub Pages serves the SPA) and a _redirects file (for Netlify-style hosts).

Note

Scaffolded projects come with netlify.toml and vercel.json already set up, so you can connect the repo to Netlify or Vercel and deploy with zero extra configuration. Deployment specifics and hosting trade-offs are covered in the Admin Guide.

10. The VS Code Extension

Install the official Slidev extension for VS Code to author and preview decks side-by-side with your editor. It provides:

• A Slides panel to browse and reorder your deck.
• Click-to-focus: jump between the editor and a live preview, in sync.
• Commands (open the command palette and type "Slidev"): start the dev server, choose or add a slides entry, go to next/previous slide, refresh or open the preview, and configure the preview port.
• A folding view that collapses slides in the editor.
• Markdown frontmatter validation via a bundled language server.

Key settings (search "Slidev" in VS Code settings):

Tip

The extension also registers AI language-model tools (for editors with AI assistants), letting an assistant query your active deck — list slide titles, fetch a slide's content, or find a slide by title.

11. Configuring the Deck

The first slide's frontmatter (the headmatter) configures the entire presentation. Common options:

---
theme: seriph
title: My Talk
titleTemplate: '%s - Slidev'
author: Jane Developer
info: |
  ## My Talk
  A short description shown on the built site.
transition: slide-left
lineNumbers: true
colorSchema: auto      # auto | light | dark
aspectRatio: 16/9
canvasWidth: 980
download: true         # show a Download PDF button on the built site
---

This guide lists only the everyday keys. The complete configuration reference — every option, its type, default, and effect (highlighter, drawings, fonts, Monaco, SEO meta, remote, router mode, and more) — is in the Slidev Admin Guide.

12. Command Reference

Slidev is invoked as slidev <command> [entry]. The entry defaults to slides.md.

Dev-server options (slidev)

Build options (slidev build)

(Build also accepts the export options below, used when --download produces the PDF.)

13. Troubleshooting

Error: The exporting for Slidev is powered by Playwright, please install it via \npm i -D playwright-chromium``

Cause: You ran slidev export (or built with --download) but the Playwright browser engine is not installed. Solution: npm install -D playwright-chromium, then re-run the export. Prevention: Scaffolded projects pre-approve Playwright's install script; if you added Slidev manually, install playwright-chromium before exporting.

Error: Entry file "…" does not exist and cannot prompt for confirmation

Cause: The entry Markdown file does not exist and you are in a non-interactive terminal (CI, a script), so Slidev cannot ask whether to create it. Solution: Create the file (or pass an existing path). Interactively, Slidev offers to generate it from a template. Prevention: Reference an existing slides.md, or commit your entry file.

Error: Base URL must start and end with a slash "/"

Cause: A --base value that does not begin and end with /. Solution: Use --base /talk/, not --base talk or --base /talk.

Error: Invalid aspect ratio "…"

Cause: The aspectRatio value could not be parsed. Solution: Use a ratio like 16/9, 1:1, or 3x4, or a plain number.

Error: Cannot eject theme "none" / Theme is already ejected

Cause: slidev theme eject was run with no real theme, or with a theme that is already a local folder. Solution: Set a packaged theme: (e.g. default, seriph) before ejecting; if it is already local, edit the files in your theme/ folder directly.

Error: "prism" support has been dropped. Please use "highlighter: shiki" instead

Cause: An old deck sets highlighter: prism. Solution: Change it to highlighter: shiki. (The legacy shikiji value is also auto-migrated to shiki with a warning.)

The dev server keeps restarting

Cause: Slidev restarts automatically when certain config or setup files change (theme, router mode, fonts, CSS, editor, SEO meta, and files like setup/shiki.ts, uno.config.ts, or vite.config.ts), or when files are added/removed. Solution: This is expected after edits to those files. If it loops, check that a watched setup/config file is not being rewritten by another tool.

A code block won't run / Monaco editor doesn't appear

Cause: Monaco is only loaded on slides that use {monaco} or {monaco-run}, and is enabled by default — but a deck-level monaco: false disables it. Solution: Ensure the code fence includes {monaco}/{monaco-run} and that the headmatter has not set monaco: false.

Note

Many real-world issues are tracked on GitHub. Search github.com/slidevjs/slidev/issues for your symptom — for example, first-run slidev --open quirks on Windows (#2582) or assets in the public/ folder (#2616).

14. FAQ

Q: Do I need to know Vue to use Slidev? No. You write Markdown. Vue is available when you want interactivity or custom components, but plain Markdown decks are fully supported.

Q: Where do I put my slides? In a single Markdown file, slides.md by default. Point Slidev at a different file by passing it as the entry argument: slidev mytalk.md.

Q: How do I split a long deck into multiple files? Use the src frontmatter key to import other Markdown files, optionally with a slide range (src: ./part2.md#1-5). See §3.9.

Q: How do I show content step by step? Wrap it in <v-click> or <v-clicks>, or use line-by-line code highlighting like {1|2|3}. See §3.7 and §3.4.

Q: Can the audience edit and run code during my talk? Yes — use {monaco} for an editable editor and {monaco-run} for one that executes.

Q: How do I export to PDF? Install playwright-chromium, then run slidev export. Add --with-clicks to capture each animation step and --with-toc for a clickable outline.

Q: How do I export to PowerPoint? slidev export --format pptx. Each slide becomes an image and your speaker notes are carried into the PPTX notes pane.

Q: How do I publish my deck as a website? slidev build produces a static site in dist/. Deploy it to Netlify, Vercel, GitHub Pages, or any static host. Use --base and --router-mode hash for sub-path deploys.

Q: How do I present from my phone or another device? Run slidev --remote to expose the deck on your network (add a password for safety), then open the printed URL — or press c for a QR code. Add --tunnel for a temporary public URL.

Q: How do I change the theme? Set theme: on the first slide (e.g. theme: seriph). Run slidev theme eject to copy a theme locally and customize it.

Q: How do I add speaker notes? Put them in an HTML comment at the end of the slide. They appear in presenter mode and can be exported with slidev export-notes.

Q: Can I write math and diagrams? Yes — LaTeX via $…$/$$…$$ (KaTeX), Mermaid via a mermaid code block, and PlantUML via a plantuml code block.

Q: How do I change the slide size/shape? Set aspectRatio (e.g. 16/9, 1:1) and canvasWidth in the headmatter.

Q: My export looks different from the live deck — why? Export renders in a headless browser. Try --wait/--wait-until to give late-loading content (iframes, charts) time, and --per-slide for decks with global components.

Q: Is Slidev free? What's the license? Slidev is open source under the MIT License (© 2021 Anthony Fu).

15. Where to Go Next

• Slidev Admin Guide — full configuration reference, architecture, custom layouts and components, setup hooks, deployment operations, and security considerations.
• The always-current official documentation lives at sli.dev.