插件扩展

VitePress 支持通过插件和 Markdown 扩展来增强功能。

版本说明

• 本文档基于 VitePress v1.0.0+ 编写
• 部分插件需要 VitePress v1.0.0 及以上版本
• 请查看各插件的官方文档获取详细版本要求和支持环境

Markdown 插件

数学公式

安装依赖：

npm add -D markdown-it-mathjax3

配置：

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'
import mathjax3 from 'markdown-it-mathjax3'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(mathjax3)
    }
  }
})

使用：

行内公式：$E = mc^2$

块级公式：
$$
\frac{\partial f}{\partial x} = \lim_{\Delta x \to 0} \frac{f(x + \Delta x) - f(x)}{\Delta x}
$$

Mermaid 图表

安装：

npm add -D vitepress-plugin-mermaid

配置：

// docs/.vitepress/config.mts
import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid(defineConfig({
  // 配置
}))

使用：

```mermaid
graph TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E
```

图片缩放

安装：

npm add -D medium-zoom

配置：

// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import mediumZoom from 'medium-zoom'
import { onMounted, watch, nextTick } from 'vue'
import { useRoute } from 'vitepress'

export default {
  extends: DefaultTheme,
  setup() {
    const route = useRoute()

    const initZoom = () => {
      mediumZoom('.main img', { background: 'var(--vp-c-bg)' })
    }

    onMounted(() => {
      initZoom()
    })

    watch(
      () => route.path,
      () => nextTick(() => initZoom())
    )
  }
}

Vite 插件

PWA 支持

安装：

npm add -D vite-plugin-pwa

配置：

// docs/.vitepress/config.mts
import { withPwa } from '@vite-pwa/vitepress'

export default withPwa(defineConfig({
  pwa: {
    registerType: 'autoUpdate',
    workbox: {
      globPatterns: ['**/*.{css,js,html,svg,png,ico,woff2}']
    },
    manifest: {
      name: 'VitePress 学习指南',
      short_name: 'VitePress',
      icons: [
        {
          src: '/logo.svg',
          sizes: '192x192',
          type: 'image/svg+xml'
        }
      ]
    }
  }
}))

Google Analytics

// docs/.vitepress/config.mts
export default defineConfig({
  head: [
    [
      'script',
      { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX' }
    ],
    [
      'script',
      {},
      `window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');`
    ]
  ]
})

百度统计

// docs/.vitepress/config.mts
export default defineConfig({
  head: [
    [
      'script',
      {},
      `var _hmt = _hmt || [];
      (function() {
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?YOUR_ID";
        var s = document.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(hm, s);
      })();`
    ]
  ]
})

自定义 Markdown 扩展

创建容器

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

export default defineConfig({
  markdown: {
    config: (md) => {
      // 自定义容器
      md.use(require('markdown-it-container'), 'details', {
        validate: function(params) {
          return params.trim().match(/^details\s+(.*)$/)
        },
        render: function(tokens, idx) {
          const m = tokens[idx].info.trim().match(/^details\s+(.*)$/)
          if (tokens[idx].nesting === 1) {
            return '<details class="custom-details"><summary>' + md.utils.escapeHtml(m[1]) + '</summary>\n'
          } else {
            return '</details>\n'
          }
        }
      })
    }
  }
})

代码复制按钮

// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  setup() {
    // 代码复制功能已内置
  }
}

VitePress 内置代码复制功能，无需额外配置。

常用插件推荐

插件版本要求

插件	用途	VitePress 版本	Node.js 版本
vitepress-plugin-mermaid	Mermaid 图表	v1.0.0+	≥ 16.0.0
markdown-it-mathjax3	数学公式	v0.20.0+	≥ 14.0.0
medium-zoom	图片缩放	v0.20.0+	≥ 12.0.0
@vite-pwa/vitepress	PWA 支持	v1.0.0+	≥ 16.0.0
unplugin-vue-components	组件自动导入	v0.20.0+	≥ 14.0.0
vite-plugin-inspect	Vite 调试工具	v0.20.0+	≥ 14.0.0

环境要求

运行环境	最低版本	推荐版本
Node.js	18.0.0	20.x LTS
npm	9.0.0	最新版本
pnpm	8.0.0	最新版本
yarn	1.22.0	最新版本

评论系统

环境要求

评论系统需要以下环境：

• Node.js 16.0.0+
• VitePress 1.0.0+
• 相关服务（如 GitHub Discussions、Waline 服务器等）

Giscus

安装：

npm add -D @giscus/vue

组件：

<!-- docs/.vitepress/theme/components/Comment.vue -->
<script setup>
import Giscus from '@giscus/vue'
import { useData } from 'vitepress'

const { isDark } = useData()
</script>

<template>
  <div class="giscus-container">
    <Giscus
      repo="user/repo"
      repo-id="YOUR_REPO_ID"
      category="Announcements"
      category-id="YOUR_CATEGORY_ID"
      mapping="pathname"
      :theme="isDark ? 'dark' : 'light'"
    />
  </div>
</template>

使用：

<!-- docs/.vitepress/theme/Layout.vue -->
<script setup>
import DefaultTheme from 'vitepress/theme'
import Comment from './components/Comment.vue'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #doc-after>
      <Comment />
    </template>
  </Layout>
</template>

Waline

安装：

npm add -D @waline/client

组件：

<script setup>
import { init } from '@waline/client'
import { onMounted, watch } from 'vue'
import { useData } from 'vitepress'

const { isDark } = useData()

onMounted(() => {
  init({
    el: '#waline',
    serverURL: 'https://your-waline-server.vercel.app',
    dark: '.dark'
  })
})
</script>

<template>
  <div id="waline" />
</template>

自定义插件

创建 VitePress 插件

// my-plugin/index.ts
import type { Plugin } from 'vite'

export function myPlugin(): Plugin {
  return {
    name: 'vitepress-plugin-custom',
    
    // Vite 钩子
    configResolved(config) {
      console.log('Config resolved:', config)
    },
    
    // 构建钩子
    transform(code, id) {
      // 转换代码
      return code
    }
  }
}

使用：

// docs/.vitepress/config.mts
import { myPlugin } from './plugins/my-plugin'

export default defineConfig({
  vite: {
    plugins: [myPlugin()]
  }
})

插件开发最佳实践

1. 命名规范：使用 vitepress-plugin- 前缀
2. 类型支持：提供 TypeScript 类型定义
3. 文档完善：提供 README 和使用示例
4. 配置灵活：支持自定义选项
5. 性能优化：避免不必要的处理

下一步

恭喜你完成了 VitePress 学习之旅！现在你可以：

• 开始构建自己的文档站点
• 探索更多高级特性
• 参与社区贡献