szeyu/slidev-syntax-guide

Slidev Syntax Guide

This skill covers Slidev's extended Markdown syntax, including slide separators, frontmatter, notes, MDC syntax, and all the special formatting features available.

When to Use This Skill

• Learning Slidev's Markdown extensions
• Writing complex slide content
• Using advanced formatting features
• Troubleshooting syntax issues
• Converting standard Markdown to Slidev format

Slide Separators

Basic Separator

Use three dashes with blank lines:

# Slide 1

Content here

---

# Slide 2

More content

Separator with Frontmatter

Add per-slide configuration:

# Slide 1

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

# Centered Blue Slide

Frontmatter

Global Configuration (First Slide)

---
theme: seriph
title: My Presentation
info: |
  ## Presentation Description
  Multi-line info text
colorSchema: auto
highlighter: shiki
drawings:
  persist: false
transition: slide-left
mdc: true
---

Per-Slide Configuration

---
layout: two-cols
class: my-custom-class
transition: fade
clicks: 3
disabled: false
hide: false
---

Common Frontmatter Options

| Option | Type | Description | |--------|------|-------------| | layout | string | Slide layout name | | class | string | CSS classes | | transition | string | Slide transition | | background | string | Background image/color | | clicks | number | Total clicks for slide | | disabled | boolean | Disable slide | | hide | boolean | Hide from navigation | | preload | boolean | Preload heavy content |

Speaker Notes

Comment Syntax

# My Slide

Visible content

<!--
These are speaker notes.
- Point to remember
- Another point

Supports **Markdown** formatting.
-->

Notes Position

Notes must be at the end of the slide, after all content.

MDC Syntax (Markdown Components)

Enable in frontmatter:

---
mdc: true
---

Inline Styles

This is [important text]{.text-red-500.font-bold}

This has a [tooltip]{title="Hover me!"}

Block Styles

::div{.flex.gap-4}
Content inside a flex container
::

::section{#my-section .bg-blue-100}
Section with ID and class
::

Component Syntax

:Icon{name="carbon:arrow-right" size="24"}

::Alert{type="warning"}
Warning message here
::

Lists

Standard Lists

- Item 1
- Item 2
  - Nested item
  - Another nested
- Item 3

1. First
2. Second
3. Third

Click-Animated Lists

<v-clicks>

- Appears first
- Appears second
- Appears third

</v-clicks>

Or with depth:

<v-clicks depth="2">

- Parent 1
  - Child 1.1
  - Child 1.2
- Parent 2
  - Child 2.1

</v-clicks>

Images

Basic Image

![Alt text](/images/photo.jpg)

Sized Image

![Alt text](/images/photo.jpg){width=400}

Styled Image

![Alt text](/images/photo.jpg){.rounded-lg.shadow-xl}

Background Image (via frontmatter)

---
background: /images/cover.jpg
class: text-white
---

# Title Over Image

Links

Standard Links

[Slidev Documentation](https://sli.dev)

Navigation Links

[Go to slide 5](/5)
[Go to slide with ID](#my-slide)

External Link with New Tab

<a href="https://sli.dev" target="_blank">Open in new tab</a>

Tables

| Feature | Supported |
|---------|-----------|
| Markdown | ✅ |
| Vue Components | ✅ |
| Animations | ✅ |
| Export | ✅ |

Blockquotes

> This is a quote
> spanning multiple lines

> [!NOTE]
> GitHub-style callout

Horizontal Rules

Content above

---

Content below (this also creates a new slide!)

Use <hr> for a rule without slide break:

Content above

<hr>

Content below (same slide)

HTML in Markdown

Inline HTML

This is <span class="text-red-500">red text</span> inline.

Block HTML

<div class="grid grid-cols-2 gap-4">
  <div>Column 1</div>
  <div>Column 2</div>
</div>

Escaping

Escape Code Block Markers

Use more backticks than the content:

Here's how to write a code block:

```js
const x = 1
```

Escape Frontmatter

\---
This is not frontmatter
\---

Slots Syntax

For layouts with multiple content areas:

---
layout: two-cols
---

# Left side content

::right::

# Right side content

Named Slots

---
layout: my-custom-layout
---

::header::
Header content

::default::
Main content

::footer::
Footer content

Global Layers

Top Layer (Above All Slides)

Create global-top.vue:

<template>
  <div class="absolute top-0 left-0 p-4">
    <img src="/logo.png" class="h-8" />
  </div>
</template>

Bottom Layer (Below All Slides)

Create global-bottom.vue:

<template>
  <div class="absolute bottom-0 right-0 p-4 text-sm">
    © 2025 My Company
  </div>
</template>

Scoped Styles

Add CSS for a single slide:

# Styled Slide

<style>
h1 {
  color: #2563eb;
  font-size: 3em;
}
</style>

Special Characters

Emojis

🚀 Rocket launch!
👋 Hello world!

Icons (with UnoCSS)

<carbon-arrow-right class="inline" />
<mdi-github class="text-2xl" />

Best Practices

1. Consistent Frontmatter: Use the same structure across slides
2. Meaningful IDs: Add IDs to slides you'll link to
3. Organize Notes: Keep speaker notes concise and actionable
4. Use MDC Sparingly: Don't overuse inline styles
5. Test Separators: Ensure blank lines around ---

Common Syntax Errors

❌ Missing blank lines

# Slide 1
---
# Slide 2

✓ Correct

# Slide 1

---

# Slide 2

❌ Invalid YAML

---
theme:default
---

✓ Correct YAML

---
theme: default
---

❌ Notes before content

<!--
Notes first
-->
# Heading

✓ Notes at end

# Heading

Content

<!--
Notes at the end
-->

Output Format

When writing Slidev content, follow this structure:

---
[FRONTMATTER: theme, layout, class, etc.]
---

# [SLIDE TITLE]

[MAIN CONTENT]
- Use Markdown formatting
- Include code blocks where relevant
- Add images with proper paths

[OPTIONAL: Vue components or HTML]

<!--
[SPEAKER NOTES]
- Key points to mention
- Timing notes
-->