VitePress 安装与基础功能

你现在阅读的课程网站（包括本页）就是用 VitePress 构建的。本周我们刚在 markdown 里用 HTML 对照过 Markdown——本任务是"内容 → 网站"流水线的第一段：装上 VitePress，看 markdown 如何变成 html，并配出站点的骨架（导航与侧栏）。

元信息

• 目标：掌握 VitePress 的安装与开发/构建流程，理解"文件路径即 URL"，能配置 nav 导航与 sidebar 侧栏
• 关键概念：静态网站生成器（SSG）、构建（build）、config.mts、nav、sidebar
• 关联阶段：cp1
• 常见误区：以为网站必须有一台"运行中"的服务器（VitePress 的构建产物是纯静态文件）；以为导航和侧栏写进了 markdown（它们来自配置文件，md 只管内容）

安装与启动

前置：Node 18+（安装见Node 环境构建）。

mkdir mysite && cd mysite
npm init -y
npm add -D vitepress
npx vitepress init     # 向导：目录回车默认，填站点标题，主题选 Default
npm run docs:dev       # 开发服务器，浏览器打开提示的地址

npx vitepress init 生成的骨架：

mysite/
├─ index.md          # 站点首页，也是第一篇 markdown
├─ .vitepress/
│  └─ config.mts     # 站点配置：标题、导航、主题选项
└─ package.json

此后每个 md 文件就是一个页面，文件路径即 URL（guide.md → /guide）。在编辑器里改一行 index.md，浏览器立刻更新——这就是 markdown 里说过的渲染器在工作，只不过输出的不是一段 html 片段，而是套上导航、侧边栏的完整页面。

从 md 到 html：构建

开发服务器的实时转换只服务于写作；build 才是"从内容到网站"的正式一步：

npm run docs:build    # 产物在 .vitepress/dist/
npm run docs:preview  # 本地预览构建产物

打开 dist/index.html 读源码，对照你的 md：

markdown 侧	dist 里的 html 侧
# 标题	<h1>标题</h1>，还带上了锚点链接
frontmatter 的 title	<title> 与 <meta>——元数据进了"head"，正如 markdown 所说：frontmatter 是给处理软件读的
每个 md 文件	一个 URL、一个完整页面（导航 + 侧边栏 + 正文 + 上/下页）

dist/ 里只有 html/css/js/图片，没有任何需要"运行"的东西——把它扔给任意静态服务器即可上线（见静态Web服务器）。这类"构建时生成静态页面"的工具就叫静态网站生成器（SSG）。

基础功能：导航与侧栏

页面有了，一个像样的站点还需要两样骨架：顶部导航（nav）与侧边目录（sidebar）。它们不写在任何 md 里，而写在 .vitepress/config.mts 的 themeConfig 中：

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '笔记', link: '/notes/' },
      { text: '关于', link: '/about/' },
    ],
    sidebar: [
      {
        text: '笔记',
        items: [
          { text: '第一篇', link: '/notes/one' },
          { text: '第二篇', link: '/notes/two' },
        ],
      },
    ],
  },
})

• nav：顶栏菜单，link 指向站内路径（不带 .md、不带 .html）
• sidebar：侧栏分组列表，每组 text 是组标题、items 是条目——本课程网站的侧栏也是这么来的，只是条目由脚本按目录结构自动生成
• 改一处 config、保存，dev 服务器立刻刷新：导航与侧栏同样是在构建期注入的骨架，md 一字不动

验收标准

• [ ] 本地 docs:dev 跑起来，改一行 md 看到热更新
• [ ] docs:build 后，在 dist/ 里找到某篇 md 对应的 html，指认 # → <h1>、frontmatter → <head> 的对应关系
• [ ] 配出至少两项 nav 与一组 sidebar，站内点得通