VitePress语法总结

概述

VitePress是基于Vite和Vue 3的静态站点生成器，专为技术文档设计。本文档总结了VitePress的核心语法和配置。

配置文件 (config.mjs)

基础配置

javascript

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '网站标题',
  description: '网站描述',
  lang: 'zh-CN',
  base: '/repository-name/', // GitHub Pages部署时需要
  
  // 主题配置
  themeConfig: {
    // 导航栏
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/', activeMatch: '/guide/' }
    ],
    
    // 侧边栏
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          collapsed: false,
          items: [
            { text: '介绍', link: '/guide/introduction' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ]
    }
  }
})

导航栏配置

javascript

nav: [
  // 简单链接
  { text: '首页', link: '/' },
  
  // 带activeMatch的链接（子页面高亮）
  { text: '指南', link: '/guide/', activeMatch: '/guide/' },
  
  // 下拉菜单
  {
    text: '更多',
    items: [
      { text: 'GitHub', link: 'https://github.com' },
      { text: '更新日志', link: '/changelog' }
    ]
  }
]

侧边栏配置

javascript

sidebar: {
  // 为不同路径配置不同侧边栏
  '/guide/': [
    {
      text: '基础',
      collapsed: false, // 默认展开
      items: [
        { text: '快速开始', link: '/guide/getting-started' },
        { text: '配置', link: '/guide/configuration' }
      ]
    },
    {
      text: '进阶',
      collapsed: true, // 默认折叠
      items: [
        { text: '主题定制', link: '/guide/theming' },
        { text: '插件开发', link: '/guide/plugins' }
      ]
    }
  ],
  '/api/': [
    // API文档的侧边栏配置
  ]
}

社交链接

javascript

socialLinks: [
  { icon: 'github', link: 'https://github.com/username/repo' },
  { icon: 'twitter', link: 'https://twitter.com/username' },
  // 自定义图标
  {
    icon: {
      svg: '<svg>...</svg>'
    },
    link: 'https://example.com',
    ariaLabel: '自定义链接'
  }
]

Frontmatter

页面配置

yaml

---
title: 页面标题
description: 页面描述
layout: doc
sidebar: false
outline: deep
lastUpdated: true
---

首页配置

yaml

---
layout: home
hero:
  name: 项目名称
  text: 项目标语
  tagline: 项目描述
  image:
    src: /logo.png
    alt: Logo
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/getting-started
    - theme: alt
      text: 在GitHub查看
      link: https://github.com/username/repo

features:
  - icon: ⚡️
    title: 快速
    details: 基于Vite的极速开发体验
  - icon: 🛠️
    title: 灵活
    details: 高度可定制的主题和配置
---

内置组件

信息框

markdown

::: info 信息
这是一个信息框
:::

::: tip 提示
这是一个提示框
:::

::: warning 警告
这是一个警告框
:::

::: danger 危险
这是一个危险警告框
:::

::: details 点击查看详情
这是一个可折叠的详情框
:::

代码组

markdown

::: code-group

```js [config.js]
export default {
  name: 'config'
}

export default {
  name: 'config'
} as const

:::


### 自定义容器

```markdown
::: warning 自定义标题
自定义内容
:::

::: danger STOP
危险区域，请勿继续
:::

链接和导航

内部链接

markdown

<!-- 相对路径 -->
[链接文本](./other-page.md)
[链接文本](../parent/page.md)

<!-- 绝对路径 -->
[链接文本](/guide/getting-started.md)

<!-- 锚点链接 -->
[跳转到标题](#标题名称)
[跳转到自定义锚点](./page.md#custom-anchor)

外部链接

markdown

[GitHub](https://github.com)
[GitHub](https://github.com){target="_blank"}

图片处理

基础图片

markdown

![Alt文本](./images/screenshot.png)
![Alt文本](/public/images/logo.png)

响应式图片

markdown

<img src="./images/screenshot.png" alt="截图" style="max-width: 100%; height: auto;">

表格增强

markdown

| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| 内容 | 内容 | 内容 |

数学公式

markdown

<!-- 行内公式 -->
这是行内公式 $E = mc^2$

<!-- 块级公式 -->
$$
\frac{1}{2} \times \frac{3}{4} = \frac{3}{8}
$$

代码高亮

基础语法高亮

markdown

```js
const message = 'Hello VitePress'
console.log(message)


### 行号和高亮

```markdown
```js{1,3-4}
const a = 1 // 高亮
const b = 2
const c = 3 // 高亮
const d = 4 // 高亮


### 聚焦代码

```markdown
```js
function foo() {
  console.log('focused') // [!code focus]
}


## 自定义样式

### CSS变量

```css
:root {
  --vp-c-brand-1: #646cff;
  --vp-c-brand-2: #747bff;
  --vp-c-brand-3: #9499ff;
}

组件样式

vue

<style>
.custom-block {
  padding: 16px;
  border-radius: 8px;
  background: var(--vp-c-bg-soft);
}
</style>

部署配置

GitHub Pages

javascript

// config.mjs
export default defineConfig({
  base: '/repository-name/',
  build: {
    outDir: 'dist'
  }
})

GitHub Actions

yaml

# .github/workflows/deploy.yml
name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run docs:build
      - uses: actions/upload-pages-artifact@v2
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v2

插件和扩展

搜索插件

javascript

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

PWA支持

javascript

import { defineConfig } from 'vitepress'
import { withPwa } from '@vite-pwa/vitepress'

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

最佳实践

文件组织

docs/
├── .vitepress/
│   ├── config.mjs
│   └── theme/
│       ├── index.js
│       └── style.css
├── guide/
│   ├── index.md
│   └── getting-started.md
├── api/
│   └── index.md
└── index.md

性能优化

图片优化: 使用WebP格式，压缩图片大小
代码分割: 合理组织页面结构
缓存策略: 配置适当的缓存头
懒加载: 大型页面使用懒加载

SEO优化

javascript

export default defineConfig({
  head: [
    ['meta', { name: 'keywords', content: '关键词1, 关键词2' }],
    ['meta', { name: 'author', content: '作者名' }],
    ['meta', { property: 'og:title', content: '页面标题' }],
    ['meta', { property: 'og:description', content: '页面描述' }]
  ]
})

常见问题

路径问题

使用相对路径时注意当前文件位置
公共资源放在 public 目录下
图片路径推荐使用相对路径

构建问题

检查Node.js版本兼容性
清理缓存: rm -rf node_modules/.vite
检查文件名中的特殊字符

部署问题

GitHub Pages需要设置正确的base路径
确保所有链接使用正确的路径格式
检查文件名是否包含不支持的字符

高级功能

自定义主题

javascript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    // 应用级别的增强
  }
}

自定义组件

vue

<!-- .vitepress/theme/components/CustomComponent.vue -->
<template>
  <div class="custom-component">
    <h3>{{ title }}</h3>
    <slot />
  </div>
</template>

<script setup>
defineProps(['title'])
</script>

多语言支持

javascript

export default defineConfig({
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN'
    },
    en: {
      label: 'English',
      lang: 'en-US',
      themeConfig: {
        nav: [
          { text: 'Guide', link: '/en/guide/' }
        ]
      }
    }
  }
})

自定义容器

markdown

::: theorem 定理
这是一个数学定理
:::

::: proof 证明
这是定理的证明过程
:::

团队页面

yaml

---
layout: page
---

<script setup>
import { VPTeamPage, VPTeamPageTitle, VPTeamMembers } from 'vitepress/theme'

const members = [
  {
    avatar: 'https://github.com/username.png',
    name: '姓名',
    title: '职位',
    links: [
      { icon: 'github', link: 'https://github.com/username' }
    ]
  }
]
</script>

<VPTeamPage>
  <VPTeamPageTitle>
    <template #title>团队成员</template>
  </VPTeamPageTitle>
  <VPTeamMembers :members="members" />
</VPTeamPage>

VitePress语法总结 ​

概述 ​

配置文件 (config.mjs) ​

基础配置 ​

导航栏配置 ​

侧边栏配置 ​

社交链接 ​

Frontmatter ​

页面配置 ​

首页配置 ​

内置组件 ​

信息框 ​

代码组 ​

链接和导航 ​

内部链接 ​

外部链接 ​

图片处理 ​

基础图片 ​

响应式图片 ​

表格增强 ​

数学公式 ​

代码高亮 ​

基础语法高亮 ​

组件样式 ​

部署配置 ​

GitHub Pages ​

GitHub Actions ​

插件和扩展 ​

搜索插件 ​

PWA支持 ​

最佳实践 ​

文件组织 ​

性能优化 ​

SEO优化 ​

常见问题 ​

路径问题 ​

构建问题 ​

部署问题 ​

高级功能 ​

自定义主题 ​

自定义组件 ​

多语言支持 ​

自定义容器 ​

团队页面 ​

VitePress语法总结

概述

配置文件 (config.mjs)

基础配置

导航栏配置

侧边栏配置

社交链接

Frontmatter

页面配置

首页配置

内置组件

信息框

代码组

链接和导航

内部链接

外部链接

图片处理

基础图片

响应式图片

表格增强

数学公式

代码高亮

基础语法高亮

组件样式

部署配置

GitHub Pages

GitHub Actions

插件和扩展

搜索插件

PWA支持

最佳实践

文件组织

性能优化

SEO优化

常见问题

路径问题

构建问题

部署问题

高级功能

自定义主题

自定义组件

多语言支持

自定义容器

团队页面