# 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](https://vuejs.org),
> [Vite](https://vite.dev), 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](https://nodejs.org) **20.12.0 or newer**.

=== "npm"

    ```bash
    npm init slidev@latest
    ```

=== "pnpm"

    ```bash
    pnpm create slidev
    ```

=== "yarn"

    ```bash
    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:

```text
  ●■▲
  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`:

```markdown
---
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:

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

```json
{
  "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:

```bash
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](https://playwright.dev). Install the browser engine when you need export:

```bash
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](#8-exporting-your-deck).

> [!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 `---`:

```markdown
# 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](#11-configuring-the-deck) and the Admin Guide).

```markdown
---
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:

````markdown
---

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

# Slide with a photo on the right
````

Per-slide frontmatter keys you will use most often:

| Key | Type | Purpose |
|---|---|---|
| `layout` | string | Layout component for this slide (see §3.3). Defaults to `cover` for slide 1, `default` otherwise. |
| `class` | string / list | CSS class(es) added to the slide root (great with UnoCSS utilities like `text-center`). |
| `transition` | string | Transition used when navigating *to* this slide (see §6.4). |
| `clicks` | number | Manually set the total number of clicks the slide needs. |
| `clicksStart` | number | Click index at which the slide's animations begin (default `0`). |
| `hide` / `disabled` | boolean | Completely hide and disable the slide. |
| `hideInToc` | boolean | Keep the slide out of the `<Toc>` component and PDF outline. |
| `title` / `level` | string / number | Override the title and heading level used by `<Toc>` and `<TitleRenderer>`. |
| `routeAlias` | string | A named alias you can link to in the URL or with `<Link>`. |
| `zoom` | number | Scale factor for the slide's content (default `1`). |
| `src` | string | Import another Markdown file as slides here (see §3.9). |
| `image` / `background` | string | Used by image/cover layouts as the slide image or background. |

> [!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:

| Layout | Use it for |
|---|---|
| `default` | Standard content slide (the default for all but the first slide). |
| `cover` | Title/opening slide (the default for slide 1). |
| `intro` | Introduce the presentation with a left-aligned title block. |
| `section` | Mark the start of a new section. |
| `center` | Center the content both axes. |
| `statement` | A single bold assertion. |
| `fact` | Highlight a big number or fact. |
| `quote` | A prominent quotation. |
| `two-cols` | Two columns (use `::right::` to fill the second). |
| `two-cols-header` | Two columns with a header spanning both. |
| `image` | A full-slide image (`image:` frontmatter). |
| `image-left` / `image-right` | Image on one side, content on the other. |
| `iframe` | A full-slide embedded web page. |
| `iframe-left` / `iframe-right` | Embedded page on one side, content on the other. |
| `full` | Use the entire canvas with no padding. |
| `end` | The closing slide. |
| `none` | No layout wrapper at all. |
| `404` / `error` | Built-in fallback slides. |

Two-column example:

```markdown
---
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](https://shiki.style) (the same engine VS Code uses), so colors match your editor
exactly.

````markdown
```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:

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

````markdown
```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](https://twoslash.netlify.app). It is enabled by default (`twoslash: true`):

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

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

`````markdown
````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](https://microsoft.github.io/monaco-editor/)
editor by adding `{monaco}`:

````markdown
```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:

````markdown
```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:

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

**LaTeX math** via [KaTeX](https://katex.org). Inline with single `$`, block with `$$`:

```markdown
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:

```markdown
<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):

```markdown
# 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 `#`:

```markdown
---
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](https://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](https://unocss.dev), so you can use utility classes
directly in your Markdown and in the `class:` frontmatter:

```markdown
---
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):

```yaml
---
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:

```yaml
---
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:
> ```bash
> 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**:

| Key | Action |
|---|---|
| `r` | Restart the server |
| `o` | Open the deck in your browser |
| `e` | Open the entry file in your editor (`$EDITOR`, defaults to VS Code) |
| `q` | Quit |
| `c` | Print a QR code for the remote-control URL (when `--remote` is on) |

### 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](https://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`.

```yaml
---
transition: slide-left
---
```

---

## 7. Presenting Live

### 7.1 The dev server

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

```bash
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:

```bash
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)

```bash
slidev export
```

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

```bash
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`:

```bash
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

| Flag | Meaning |
|---|---|
| `--output <path>` | Output file path. |
| `--format <pdf\|png\|pptx\|md>` | Output format (default `pdf`). |
| `--range <pages>` | Pages to export, e.g. `1,4-5,6`. |
| `--dark` | Export using the dark color scheme. |
| `--with-clicks`, `-c` | Emit a page for every click step. |
| `--with-toc` | Include a document outline/table of contents (PDF). |
| `--per-slide` | Render slide-by-slide (better for some global components, but breaks cross-slide links and the PDF TOC). |
| `--scale <n>` | Resolution scale factor for image export. |
| `--omit-background` | Transparent background for PNG export. |
| `--timeout <ms>` | Per-page render timeout (default 30000). |
| `--wait <ms>` | Extra wait before capturing each slide. |
| `--wait-until <event>` | `networkidle` (default), `load`, `domcontentloaded`, or `none`. |
| `--executable-path <path>` | Use a specific browser instead of Playwright's bundled one. |

### 8.4 Exporting speaker notes

```bash
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:

```bash
slidev build
```

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

```bash
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:

```bash
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](https://marketplace.visualstudio.com/)
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):

| Setting | Purpose |
|---|---|
| `slidev.port` | Preview server port. |
| `slidev.include` / `slidev.exclude` | Glob patterns for which Markdown files are Slidev decks. |
| `slidev.preview-sync` | Keep the preview in sync with the cursor. |
| `slidev.annotations` | Show inline slide annotations. |
| `slidev.dev-command` | Override the command used to start the dev server. |

> [!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:

```yaml
---
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`.

| Command | What it does |
|---|---|
| `slidev [entry]` | Start the dev server and presenter (the default command). |
| `slidev build [entry]` | Build a hostable single-page app into `dist/`. |
| `slidev export [entry]` | Export slides to PDF/PNG/PPTX/Markdown. |
| `slidev export-notes [entry]` | Export speaker notes to a PDF. |
| `slidev format [entry]` | Reformat the Markdown file through Slidev's parser. |
| `slidev theme eject` | Copy the current theme into a local `theme/` folder for editing. |

### Dev-server options (`slidev`)

| Option | Default | Meaning |
|---|---|---|
| `--port`, `-p` | `3030` | Port to serve on. |
| `--open`, `-o` | `false` | Open the browser on start. |
| `--remote [password]` | — | Listen on the network; optional presenter password. |
| `--tunnel` | `false` | Open a Cloudflare Quick Tunnel (requires `--remote`). |
| `--bind` | `0.0.0.0` | Which IP to listen on in remote mode. |
| `--log` | `warn` | Log level: `error`, `warn`, `info`, `silent`. |
| `--inspect` | `false` | Enable the Vite inspect plugin for debugging. |
| `--force`, `-f` | `false` | Ignore the dependency-optimizer cache and re-bundle. |
| `--base` | `/` | Base URL (must start and end with `/`). |
| `--theme`, `-t` | — | Override the deck's theme. |

### Build options (`slidev build`)

| Option | Default | Meaning |
|---|---|---|
| `--out`, `-o` | `dist` | Output directory. |
| `--base` | — | Output base path (e.g. `/talk/`). |
| `--download`, `-d` | — | Bundle a downloadable PDF and show a download button. |
| `--without-notes` | — | Exclude speaker notes from the build. |
| `--router-mode` | `history` | `history` or `hash` (use `hash` for sub-directory deploys). |
| `--inspect` | `false` | Enable the Vite inspect plugin. |

(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](https://github.com/slidevjs/slidev/issues) for your
> symptom — for example, first-run `slidev --open` quirks on Windows
> ([#2582](https://github.com/slidevjs/slidev/issues/2582)) or assets in the `public/`
> folder ([#2616](https://github.com/slidevjs/slidev/issues/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](https://sli.dev).

---

_Generated June 2026 from slidevjs/slidev at a1609ff. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._