slidev-project-structure

Slidev 项目结构

此技能可帮助你了解 Slidev 项目的完整结构，包括配置文件、目录约定和自定义选项。

何时使用此技能

• 搭建复杂的 Slidev 项目
• 添加自定义组件或布局
• 配置主题和扩展
• 了解资源和样式的存放位置
• 排查项目结构问题

标准项目结构

my-presentation/
├── slides.md              # Main presentation file
├── package.json           # Project dependencies
├── components/            # Custom Vue components
│   └── Counter.vue
├── layouts/               # Custom layouts
│   └── my-layout.vue
├── pages/                 # Additional slide files
│   └── intro.md
├── public/                # Static assets
│   ├── images/
│   └── favicon.ico
├── styles/                # Global styles
│   └── index.css
├── setup/                 # Setup scripts
│   ├── main.ts           # Vue app setup
│   ├── monaco.ts         # Monaco editor setup
│   └── shiki.ts          # Shiki highlighter setup
├── snippets/              # External code snippets
│   └── example.ts
├── .slidev/               # Generated files (gitignore)
│   └── drawings/         # Persisted drawings
├── vite.config.ts         # Vite configuration
├── uno.config.ts          # UnoCSS configuration
└── netlify.toml           # Deployment config (optional)

核心文件

slides.md

包含所有幻灯片的主演示文稿文件：

---
theme: seriph
title: My Presentation
---

# Slide 1

---

# Slide 2

package.json

必要的脚本和依赖项：

{
  "name": "my-presentation",
  "private": true,
  "scripts": {
    "dev": "slidev --open",
    "build": "slidev build",
    "export": "slidev export"
  },
  "dependencies": {
    "@slidev/cli": "^0.50.0",
    "@slidev/theme-seriph": "^0.25.0"
  }
}

全局配置

Headmatter（第一页）

第一页的 frontmatter 用于配置整个演示文稿：

---
# Theme
theme: seriph
addons:
  - slidev-addon-excalidraw

# Metadata
title: My Presentation
titleTemplate: '%s - Slidev'
info: |
  ## Slidev Starter Template
  Presentation slides for developers.

# Appearance
colorSchema: auto
aspectRatio: 16/9
canvasWidth: 980
themeConfig:
  primary: '#5d8392'

# Code
highlighter: shiki
lineNumbers: true
monaco: true

# Features
drawings:
  enabled: true
  persist: true
  presenterOnly: false
  syncAll: true
selectable: true
record: true

# Navigation
transition: slide-left
clicks: auto

# Export
exportFilename: my-presentation
download: true

# Layout
layout: cover
background: /cover.jpg
class: text-center
---

目录约定

components/

自动导入幻灯片的自定义 Vue 组件：

<script setup lang="ts">
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <div class="flex items-center gap-4">
    <button @click="count--">-</button>
    <span>{{ count }}</span>
    <button @click="count++">+</button>
  </div>
</template>

在幻灯片中使用：

# Interactive Counter

<Counter />

layouts/

自定义布局可扩展内置布局：

<template>
  <div class="slidev-layout my-intro">
    <div class="header">
      <slot name="header" />
    </div>
    <div class="main">
      <slot />
    </div>
    <div class="footer">
      <slot name="footer">
        <span>My Company</span>
      </slot>
    </div>
  </div>
</template>

<style scoped>
.my-intro {
  display: grid;
  grid-template-rows: auto 1fr auto;
  height: 100%;
  padding: 2rem;
}
</style>

在幻灯片中使用：

---
layout: my-intro
---

::header::
# Welcome

::default::
Main content here

::footer::
Custom footer

public/

通过根 URL 提供的静态资源：

public/
├── images/
│   ├── logo.png        # Use: /images/logo.png
│   └── diagram.svg
├── favicon.ico         # Use: /favicon.ico
└── data.json           # Use: /data.json

styles/

应用于所有幻灯片的全局样式：

/* styles/index.css */
@import url('https://fonts.googleapis.com/css2?family=Inter&display=swap');

:root {
  --slidev-theme-primary: #3b82f6;
}

.slidev-layout {
  font-family: 'Inter', sans-serif;
}

/* Custom utility classes */
.highlight {
  background: linear-gradient(120deg, #84fab0 0%, #8fd3f4 100%);
  padding: 0 0.25em;
}

setup/

配置脚本：

// setup/main.ts - Vue app configuration
import { defineAppSetup } from '@slidev/types'

export default defineAppSetup(({ app, router }) => {
  // Register global components
  // Configure plugins
})

// setup/shiki.ts - Code highlighter
import { defineShikiSetup } from '@slidev/types'

export default defineShikiSetup(() => {
  return {
    themes: {
      dark: 'vitesse-dark',
      light: 'vitesse-light',
    },
  }
})

// setup/monaco.ts - Monaco editor
import { defineMonacoSetup } from '@slidev/types'

export default defineMonacoSetup(() => {
  return {
    editorOptions: {
      fontSize: 14,
      minimap: { enabled: false },
    },
  }
})

pages/

用于模块化演示文稿的其他幻灯片文件：

# Introduction Section

---

# About Me

---

# Agenda

在主文件中导入：

---
src: ./pages/intro.md
---

---

# Main Content

---

---
src: ./pages/conclusion.md
---

Vite 配置

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  slidev: {
    vue: {
      // Vue plugin options
    },
  },
  // Standard Vite options
  server: {
    port: 3030,
  },
})

UnoCSS 配置

// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  shortcuts: {
    'bg-main': 'bg-white dark:bg-slate-900',
    'text-main': 'text-slate-900 dark:text-slate-100',
  },
  theme: {
    colors: {
      primary: '#3b82f6',
    },
  },
})

主题配置

使用主题

---
theme: seriph
themeConfig:
  primary: '#5d8392'
  secondary: '#8b5cf6'
---

分离主题文件

自定义主题源代码：

slidev theme eject

此操作会将主题复制到你的项目中，以便完全自定义。

多文件演示文稿

导入幻灯片

---
src: ./pages/section1.md
---

---
src: ./pages/section2.md
---

合并 Frontmatter

---
src: ./pages/intro.md
title: Overridden Title
class: custom-class
---

生成的文件（.slidev/）

.slidev/ 目录包含：

• drawings/ - 已保存的绘图
• 其他生成的资源

添加到 .gitignore：

.slidev
node_modules
dist

最佳实践

1. 保持 slides.md 内容聚焦：大型演示文稿请使用 src 导入
2. 整理资源：所有图片均放在 public/images/ 中
3. 重复利用组件：为重复使用的模式创建组件
4. 版本控制：提交所有源文件，但排除 .slidev/ 和 dist/
5. 记录自定义布局：添加注释，说明插槽的用法

输出格式

说明项目结构时，请提供：

RECOMMENDED STRUCTURE:
├── slides.md           # Main file
├── components/         # Custom Vue components
├── layouts/           # Custom layouts
├── public/            # Static assets
├── styles/            # Global CSS
└── package.json       # Dependencies

KEY CONFIGURATION:
- Theme: [theme name]
- Addons: [list of addons]
- Custom components: [component names]
- Custom layouts: [layout names]

FILES TO CREATE:
1. [filename] - [purpose]
2. [filename] - [purpose]

GITIGNORE:
.slidev/
node_modules/
dist/