插件应用示例

本模板已预装多款插件。本页逐一演示它们的实际效果与基本用法。

每个插件按三部分呈现：语法说明 → 示例写法（配置 / 源码）→ 实际效果（页面上的真实表现）。

1. Mermaid 图表

语法说明：由 vitepress-plugin-mermaid 提供，用 ```mermaid 代码块即可绘制图表，支持 flowchart / sequence / gantt / class / state / pie 等多种图。在 config.ts 中通过 withMermaid(defineConfig({...})) 启用。

流程图

示例写法：

```mermaid
flowchart LR
  A[开始] --> B{是否登录?}
  B -->|是| C[进入控制台]
  B -->|否| D[跳转登录]
  D --> C
  C --> E[结束]
```

实际效果：

时序图

示例写法：

```mermaid
sequenceDiagram
  participant U as 用户
  participant B as 浏览器
  participant S as 服务器
  U->>B: 点击按钮
  B->>S: 发送请求
  S-->>B: 返回 JSON
  B-->>U: 渲染页面
```

实际效果：

甘特图

示例写法：

```mermaid
gantt
  title 文档站建设计划
  dateFormat YYYY-MM-DD
  section 搭建
  初始化模板   :done,   a1, 2026-01-01, 3d
  配置部署     :active, a2, after a1, 4d
  section 内容
  编写文档     :        a3, after a2, 7d
```

实际效果：

类图 / 状态图 / 饼图

示例写法：

```mermaid
classDiagram
  class Doc {
    +title: string
    +render()
  }
  class Page {
    +path: string
  }
  Doc <|-- Page
```

```mermaid
stateDiagram-v2
  [*] --> 草稿
  草稿 --> 评审: 提交
  评审 --> 发布: 通过
  发布 --> [*]
```

```mermaid
pie title 构建产物占比
  "JS" : 45
  "CSS" : 25
  "HTML" : 20
  "其他" : 10
```

实际效果：

2. 图片缩放（medium-zoom）

语法说明：medium-zoom 已接入主题，文档正文中的图片点击即可放大查看；加 .no-zoom 类可禁用某张图片的缩放。

示例写法：

![Logo 放大预览](/logo.svg)

![不缩放的 Logo](/logo.svg){.no-zoom}

实际效果（点击下方 Logo 试试放大，本仓库已接入 medium-zoom）：

3. 评论系统（Giscus）

语法说明：@giscus/vue 已在主题组件 GiscusComment.vue 中以 doc-after 位置自动注入，每篇文档底部显示由 GitHub Discussions 驱动的评论区（首页除外）。使用前需在组件中替换占位符，并在仓库安装 Giscus 应用、开启 Discussions。

示例写法（docs/.vitepress/theme/components/GiscusComment.vue 中的配置项）：

<Giscus
  repo="YOUR_REPO/YOUR_REPO"      // 改为你的 "owner/repo"
  repoId="YOUR_REPO_ID"           // Giscus 返回的 repoId
  category="Announcements"
  categoryId="YOUR_CATEGORY_ID"   // 分类 ID
  mapping="pathname"
  theme="preferred_color_scheme"
  lang="en"
/>

实际效果：本页底部即由该组件渲染的评论区（若尚未配置 GitHub 凭据，则会显示加载失败或空白，属正常——配置后生效）。

4. 代码组文件图标（group-icons）

语法说明：vitepress-plugin-group-icons 已启用（config.ts 中 markdown.codeTransformers: [groupIconMdPlugin]），带文件名标注（[文件名]）的代码块会自动显示对应语言 / 文件图标。

示例写法：

```ts [utils.ts]
export const sum = (a: number, b: number) => a + b
```

```json [config.json]
{ "name": "demo" }
```

```vue [Button.vue]
<template>
  <button class="btn">{{ label }}</button>
</template>
```

实际效果（每个代码块标题左侧应显示对应文件图标）：

export const sum = (a: number, b: number) => a + b

{ "name": "demo", "version": "1.0.0" }

<template>
  <button class="btn">{{ label }}</button>
</template>

5. PWA（vite-plugin-pwa）

语法说明：vite-plugin-pwa 在 docs/.vitepress/vite-plugins/pwa.ts 中配置，buildEnd 时生成 Service Worker 与 manifest.webmanifest，使站点可「安装为应用」并离线访问。

示例写法（核心配置）：

VitePWA({
  registerType: 'autoUpdate',
  manifest: {
    name: 'My Docs',
    short_name: 'My Docs',
    theme_color: '#ffffff',
    icons: [{ src: 'logo.svg', sizes: '192x192', type: 'image/svg+xml' }],
  },
  includeAssets: ['logo.svg'],
})

实际效果：部署后访问站点，浏览器地址栏会出现「安装」按钮；断网后仍可阅读已缓存页面（本模板已配置 registerType: 'autoUpdate'）。

6. Sitemap（sitemap）

语法说明：docs/.vitepress/vite-plugins/sitemap.ts 在 buildEnd 阶段扫描 dist 下所有 HTML，生成 sitemap.xml，便于搜索引擎收录。

示例写法（核心逻辑）：

export function generateSitemap(siteUrl = 'https://YOUR_REPO.github.io/YOUR_REPO/') {
  // 扫描 dist/*.html -> 写入 sitemap.xml
}

实际效果：默认站点地址占位为 https://YOUR_REPO.github.io/YOUR_REPO/，上线前请替换为真实域名；生成的 sitemap.xml 位于构建产物根目录，可直接被爬虫发现。

7. 日期工具（dayjs）

语法说明：dayjs 是轻量日期库，作为工具依赖预装在本模板中。它并非「文档渲染插件」，而是供主题或自定义组件处理时间显示（例如把 lastUpdated 时间戳格式化为本地化文案）。

示例写法：

import dayjs from 'dayjs'

dayjs().format('YYYY-MM-DD HH:mm')        // 当前时间
dayjs('2026-01-01').fromNow()             // 需引入 relativeTime 插件

说明：截至当前版本，dayjs 已预装但尚未在主题中实际接入 lastUpdated 格式化，因此页面上暂无直接可见效果，这里仅展示用法。如需启用，可在 theme/index.ts 中 import dayjs 并改写时间显示逻辑。

小结

插件	作用	本页演示
vitepress-plugin-mermaid	图表渲染	流程图 / 时序 / 甘特 / 类 / 状态 / 饼图
medium-zoom	图片点击放大	上方 Logo 可点击
@giscus/vue	文档评论	页面底部评论区
vitepress-plugin-group-icons	代码块文件图标	上方带文件名代码块
vite-plugin-pwa	离线 / 可安装 PWA	安装按钮 + 离线缓存
sitemap	生成 sitemap.xml	构建产物中查看
dayjs	日期处理工具	代码片段（尚未接入主题）