用 Slidev 把 Markdown 變成簡報網站

最近需要在會議上做簡報，與其用 PowerPoint 或 Google Slides，不如直接做成一個網站，隨時打開瀏覽器就能展示。最後選擇了 Slidev 這個框架，用 Markdown 寫投影片，搭配一些簡單的動效，最終部署成純靜態網站。

這篇文章會分享從技術選型到部署上線的過程，以及一些使用上的心得。

為什麼選 Slidev

一開始有考慮過幾個方案：

Slidev 最吸引我的地方是用 Markdown 就能寫投影片，而且如果需要更複雜的排版，隨時可以在 Markdown 裡面穿插 HTML 和 Vue 組件。內建的 UnoCSS 讓樣式也不用額外設定，寫法跟 Tailwind CSS 幾乎一樣。

建立專案

1
npm init -y
2
npm install @slidev/cli @slidev/theme-default

在 package.json 加入 scripts：

1
{
2
  "scripts": {
3
    "dev": "slidev",
4
    "build": "slidev build"
5
  }
6
}

接著建立 slides.md，這就是你的整份簡報：

1
---
2
theme: default
3
transition: slide-left
4
title: My Presentation
5
---
6

7
# Hello
8

9
This is the first slide.
10

11
---
12

13
# Second Slide
14

15
This is the second slide.

每一頁用 --- 分隔，最上面的 --- 區塊是全域設定。跑 npm run dev 就能在瀏覽器看到結果了。

投影片結構

因為這是個人簡介，內容不是技術導向，我把它設計成一個比較有節奏感的流程：文字頁和圖片頁交替出現。

1
封面 → 個人照＋簡介 → 主題文字 → 搭配照片 → 主題文字 → 搭配照片 → ... → 結尾

每個主題都拆成獨立的頁面，不會把太多東西塞在同一頁。這樣在操作的時候節奏會比較好，聽眾也比較容易跟上。

自訂樣式

Slidev 預設的樣式比較中性，如果想要有自己的風格，可以在 styles/ 資料夾裡覆寫。建立 styles/index.ts 作為進入點：

1
import './custom.css'

然後在 custom.css 裡面寫你的樣式：

1
.slidev-layout {
2
  background: #f5f0eb !important;
3
  color: #3a3a3a !important;
4
  font-family: 'Noto Sans TC', sans-serif !important;
5
}

這裡的 .slidev-layout 是每一頁投影片的最外層容器，用 !important 覆蓋預設 theme 的樣式。

如果要讓所有頁面都使用同一張背景圖，也可以直接寫在這裡：

1
.slidev-layout {
2
  background: url('/images/bg.jpg') center / cover no-repeat !important;
3
}

圖片放在 public/images/ 下，Slidev 會把 public/ 作為靜態資源的根目錄。

使用 Vue 組件

如果某些排版用純 Markdown 不好實現，可以建立 Vue 組件。把 .vue 檔放在 components/ 資料夾下，Slidev 會自動註冊，直接在 Markdown 裡面用就好：

1
<script setup lang="ts">
2
defineProps<{
3
  name: string
4
  level: number
5
}>()
6
</script>
7

8
<template>
9
  <div class="mb-4">
10
    <div class="flex justify-between mb-1">
11
      <span class="text-sm">{{ name }}</span>
12
      <span class="text-xs">{{ level }}%</span>
13
    </div>
14
    <div class="w-full rounded-full h-1.5" style="background: #d4cac0;">
15
      <div
16
        class="h-1.5 rounded-full"
17
        style="background: #8c7b6b;"
18
        :style="{ width: `${level}%` }"
19
      />
20
    </div>
21
  </div>
22
</template>

在 slides.md 裡直接使用：

1
<SkillBar name="Vue.js" :level="90" />
2
<SkillBar name="TypeScript" :level="85" />

動效

頁間切換

在全域 frontmatter 設定預設的 transition：

1
---
2
transition: slide-left
3
---

也可以在個別頁面的 frontmatter 覆寫：

1
---
2
transition: fade
3
---

逐步顯示

用 <v-click> 包住想要按下一步才出現的內容：

1
# Title
2

3
<v-click>
4

5
This text appears after clicking.
6

7
</v-click>

這在會議上很實用，可以控制資訊出現的時機，不會一次全部秀出來。

元素進場動畫

如果想要更細緻的動畫效果，可以安裝 @vueuse/motion：

1
npm install @vueuse/motion

然後在 HTML 標籤上加 v-motion directive：

1
<div v-motion
2
  :initial="{ opacity: 0, y: 15 }"
3
  :enter="{ opacity: 1, y: 0, transition: { duration: 1000 } }">
4
  Content here
5
</div>

踩到的坑

Markdown 裡的 HTML 縮排會變成 code block

這大概是最容易踩到的問題。在 slides.md 裡面寫 HTML 時，如果縮排超過 4 個空格，Markdown parser 會把它當成程式碼區塊，整段 HTML 就會被原封不動地顯示出來。

解決方法就是把巢狀 HTML 的縮排壓平，不要超過 3 個空格。雖然可讀性會差一點，但至少能正常渲染。

<p> 巢狀問題

如果在 <p> 標籤裡面放了 Markdown 文字，Slidev 會把文字解析成 <p>，導致 <p> 裡面又有 <p>，瀏覽器會報 hydration warning。解決方法是外層改用 <div>。

第一頁空白

全域 frontmatter 區塊本身也會被渲染成一頁投影片。如果你的第一頁是封面，可以直接把封面內容跟全域設定放在同一個 frontmatter 區塊裡，加上 layout: none 然後自己排版。

部署

npm run build 會在 dist/ 產出純靜態的 HTML/CSS/JS，可以部署到任何靜態網站託管服務。

我是部署到 Zeabur，連接 GitHub repo 後設定好 build command（npm run build）和 output directory（dist）就完成了。

如果是部署到 GitHub Pages 之類有 sub-path 的服務，記得在 build 時加上 --base 參數：

1
slidev build --base /your-repo-name/

操作快捷鍵

在會議上用筆電操作時，這些快捷鍵很實用：

這些都是 Slidev 內建的，不需要額外設定。

心得

用 Slidev 做簡報最大的好處是，它就是一個前端專案。想要什麼樣式就寫 CSS，想要什麼互動就寫 Vue 組件，不會被簡報軟體的功能限制住。而且因為是 Markdown，內容的維護和版本控制都很方便。

比較需要注意的是，Slidev 畢竟是把 Markdown 轉成 Vue 組件再渲染，有些 Markdown 和 HTML 混用的邊界情況會比較奇怪（像上面提到的縮排和巢狀問題），需要花一點時間摸索。

整體來說，如果你本身有前端開發的經驗，用 Slidev 做簡報會很順手，也能做出比傳統簡報軟體更有個人風格的東西。