slidev-syntax-guide（Slidev 语法指南）

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

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:

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