主题配置

默认主题提供了丰富的配置选项，可以通过 themeConfig 字段定制站点外观。

快速导航： 快速参考 | 基础配置 | 导航栏 | 侧边栏 | 社交链接 | 搜索 | 编辑链接 | 页脚 | 大纲 | 本地化 | 其他配置

快速参考

所有 themeConfig 字段一览：

字段	类型	默认值	说明
`logo`	`string`	—	站点 Logo
`siteTitle`	`string \| false`	`title` 配置	站点标题
`nav`	`NavItem[]`	—	导航栏配置
`sidebar`	`Sidebar \| SidebarMulti`	—	侧边栏配置
`socialLinks`	`SocialLink[]`	—	社交媒体链接
`search`	`SearchConfig`	本地搜索	搜索配置
`editLink`	`EditLinkConfig`	—	编辑链接配置
`footer`	`FooterConfig`	—	页脚配置
`outline`	`OutlineConfig`	`{ level: 2 }`	大纲配置
`docFooter`	`DocFooterConfig`	—	文档页脚配置
`lastUpdated`	`LastUpdatedConfig`	—	最后更新配置
`returnToTopLabel`	`string`	`'Return to top'`	返回顶部文本
`sidebarMenuLabel`	`string`	`'Menu'`	侧边栏菜单文本
`darkModeSwitchLabel`	`string`	`'Appearance'`	深色模式切换文本
`lightModeSwitchTitle`	`string`	`'Light'`	浅色模式标题
`darkModeSwitchTitle`	`string`	`'Dark'`	深色模式标题
`externalLinkIcon`	`boolean`	`false`	外部链接图标
`notFound`	`NotFoundConfig`	—	404 页面配置

基础配置

logo

类型： string
默认值： 无

站点 Logo，显示在导航栏左侧。路径相对于 public 目录。

export default defineConfig({
  themeConfig: {
    logo: '/logo.svg'
  }
})

深色模式 Logo

如需为深色模式使用不同 Logo，可通过 CSS：

css

/* .vitepress/theme/style.css */
[src$="/logo.svg"] {
  display: none;
}

.dark [src$="/logo.svg"] {
  display: none;
}

.dark [src$="/logo-dark.svg"] {
  display: inline;
}

siteTitle

类型： string | false
默认值： 站点 title 配置

导航栏显示的站点标题。设为 false 可隐藏（通常配合 Logo 使用）。

export default defineConfig({
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: '我的博客'  // 自定义标题
    // siteTitle: false   // 隐藏标题
  }
})

导航栏配置

nav

类型： NavItem[]
默认值： 无

导航栏配置，支持单层链接和下拉菜单。

单层链接

export default defineConfig({
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/reference/' }
    ]
  }
})

下拉菜单

export default defineConfig({
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      {
        text: '更多',
        items: [
          { text: '配置', link: '/reference/site-config' },
          { text: 'API', link: '/reference/runtime-api' },
          { text: 'CLI', link: '/reference/cli' }
        ]
      }
    ]
  }
})

嵌套下拉菜单

nav: [
  {
    text: '更多',
    items: [
      {
        text: '社区',
        items: [
          { text: 'GitHub', link: 'https://github.com/vuejs/vitepress' },
          { text: 'Discord', link: 'https://discord.gg/vue' }
        ]
      },
      {
        text: '资源',
        items: [
          { text: '教程', link: '/tutorial/' },
          { text: '示例', link: '/examples/' }
        ]
      }
    ]
  }
]

带徽章的导航

nav: [
  {
    text: '新功能',
    link: '/new-feature',
    badge: { text: '新', type: 'tip' }
  }
]

NavItem 类型详解

字段	类型	必需	说明
`text`	`string`	✅	导航项文本
`link`	`string`	—	链接路径（与 `items` 二选一）
`items`	`NavItem[]`	—	子菜单项（与 `link` 二选一）
`activeMatch`	`string \| RegExp`	—	自定义激活匹配规则
`target`	`string`	—	链接 `target` 属性，如 `'_blank'`
`rel`	`string`	—	链接 `rel` 属性，如 `'noopener'`
`badge`	`BadgeConfig`	—	徽章配置

BadgeConfig 字段：

字段	类型	默认值	说明
`text`	`string`	—	徽章文本
`type`	`'info' \| 'tip' \| 'warning' \| 'danger'`	`'info'`	徽章样式类型

activeMatch 示例

nav: [
  {
    text: '指南',
    link: '/guide/',
    // 匹配 /guide/ 下所有页面
    activeMatch: '/guide/'
  },
  {
    text: 'API',
    link: '/reference/',
    // 使用正则匹配多个路径
    activeMatch: '^/(reference|api)/'
  }
]

侧边栏配置

类型： Sidebar | SidebarMulti
默认值： 无

侧边栏配置，支持单侧边栏和多侧边栏两种模式。

单侧边栏

所有页面共享同一侧边栏：

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '开始',
        items: [
          { text: '介绍', link: '/guide/' },
          { text: '安装', link: '/guide/installation' },
          { text: '快速开始', link: '/guide/getting-started' }
        ]
      },
      {
        text: '进阶',
        collapsed: true,
        items: [
          { text: 'SSR', link: '/advanced/ssr' },
          { text: 'MPA', link: '/advanced/mpa' }
        ]
      }
    ]
  }
})

多侧边栏

不同路径使用不同侧边栏：

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '指南',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ],
      '/reference/': [
        {
          text: 'API 参考',
          items: [
            { text: '运行时 API', link: '/reference/runtime-api' },
            { text: '构建 API', link: '/reference/build-api' }
          ]
        }
      ]
    }
  }
})

SidebarItem 类型详解

字段	类型	必需	说明
`text`	`string`	✅	分组/链接标题
`link`	`string`	—	链接路径（与 `items` 二选一）
`items`	`SidebarItem[]`	—	子项列表（与 `link` 二选一）
`collapsed`	`boolean`	—	是否默认折叠（仅对有 `items` 的分组有效）
`base`	`string`	—	子项链接的基础路径前缀
`badge`	`BadgeConfig`	—	徽章配置
`rel`	`string`	—	链接 `rel` 属性
`target`	`string`	—	链接 `target` 属性

折叠分组

sidebar: [
  {
    text: '进阶',
    collapsed: true,  // 默认折叠
    items: [
      { text: 'SSR', link: '/advanced/ssr' },
      { text: 'MPA', link: '/advanced/mpa' }
    ]
  }
]

使用 base 简化路径

sidebar: [
  {
    text: '指南',
    base: '/guide/',
    items: [
      { text: '介绍', link: '' },           // → /guide/
      { text: '安装', link: 'installation' }, // → /guide/installation
      { text: '配置', link: 'configuration' } // → /guide/configuration
    ]
  }
]

社交链接

socialLinks

类型： SocialLink[]
默认值： 无

导航栏右侧的社交媒体图标链接。

export default defineConfig({
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/vitepress' },
      { icon: 'discord', link: 'https://discord.gg/vue' }
    ]
  }
})

内置图标

图标名称	说明
`github`	GitHub
`twitter`	Twitter / X
`discord`	Discord
`facebook`	Facebook
`instagram`	Instagram
`linkedin`	LinkedIn
`slack`	Slack
`youtube`	YouTube
`mastodon`	Mastodon

自定义 SVG 图标

socialLinks: [
  {
    icon: {
      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="..."/></svg>'
    },
    link: 'https://example.com'
  }
]

社交链接 + aria-label

socialLinks: [
  {
    icon: 'github',
    link: 'https://github.com/...',
    // 自定义无障碍标签
    ariaLabel: 'GitHub 仓库'
  }
]

SocialLink 类型详解：

字段	类型	必需	说明
`icon`	`string \| { svg: string }`	✅	图标名称或自定义 SVG
`link`	`string`	✅	链接地址
`ariaLabel`	`string`	—	无障碍标签

搜索配置

search

类型： SearchConfig
默认值： 本地搜索

VitePress 内置搜索支持，可选择本地搜索或 Algolia 搜索。

本地搜索

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        // 自定义搜索翻译
        translations: {
          button: {
            buttonText: '搜索文档'
          },
          modal: {
            noResultsText: '无法找到相关结果',
            resetButtonTitle: '清除查询条件',
            footer: {
              selectText: '选择',
              navigateText: '切换',
              closeText: '关闭'
            }
          }
        }
      }
    }
  }
})

本地搜索选项

选项	类型	默认值	说明
`translations`	`object`	—	搜索 UI 翻译
`_meta`	`object`	—	元数据配置

Algolia 搜索

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        // 可选配置
        locales: {
          zh: {
            placeholder: '搜索文档',
            translations: {
              button: { buttonText: '搜索' },
              modal: { noResultsText: '没有找到相关结果' }
            }
          }
        }
      }
    }
  }
})

Algolia 选项详解

选项	类型	必需	说明
`appId`	`string`	✅	Algolia Application ID
`apiKey`	`string`	✅	Algolia Search-Only API Key
`indexName`	`string`	✅	Algolia 索引名称
`locales`	`object`	—	多语言搜索配置
`placeholder`	`string`	—	搜索框占位文本
`searchParameters`	`object`	—	Algolia 搜索参数

编辑链接

editLink

类型： EditLinkConfig
默认值： 无

在每个页面底部显示"编辑此页"链接，引导用户参与文档贡献。

export default defineConfig({
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: '在 GitHub 上编辑此页'
    }
  }
})

EditLinkConfig 字段详解：

字段	类型	必需	说明
`pattern`	`string`	✅	编辑链接模板，`:path` 会被替换为当前页面路径
`text`	`string`	—	链接文本，默认 `'Edit this page'`

不同平台的 pattern

平台	pattern 示例
GitHub	`https://github.com/user/repo/edit/main/docs/:path`
GitLab	`https://gitlab.com/user/repo/-/edit/main/docs/:path`
Gitee	`https://gitee.com/user/repo/edit/main/docs/:path`
CNB	`https://cnb.cool/user/repo/-/edit/main/docs/:path`

页脚配置

类型： FooterConfig
默认值： 无

页面底部页脚，仅在 layout: doc 时显示。

export default defineConfig({
  themeConfig: {
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026-present 张三'
    }
  }
})

FooterConfig 字段详解：

字段	类型	说明
`message`	`string`	页脚消息（支持 HTML）
`copyright`	`string`	版权信息

页脚支持 HTML

message 字段支持 HTML 标签，可以添加链接：

footer: {
  message: '基于 <a href="https://opensource.org/licenses/MIT">MIT 许可</a>发布',
  copyright: 'Copyright © 2026-present'
}

大纲配置

outline

类型： OutlineConfig
默认值： { level: 2, label: 'On this page' }

右侧大纲（目录）配置。

export default defineConfig({
  themeConfig: {
    outline: {
      level: [2, 4],  // 显示 h2 到 h4
      label: '目录导航'
    }
  }
})

OutlineConfig 字段详解：

字段	类型	默认值	说明
`level`	`number \| [number, number]`	`2`	显示的标题级别范围
`label`	`string`	`'On this page'`	大纲标题文本

level 值说明：

值	效果
`2`	仅显示 h2
`3`	显示 h2 和 h3
`[2, 3]`	显示 h2 和 h3
`[2, 4]`	显示 h2 到 h4
`false`	不显示大纲

文档页脚

docFooter

类型： DocFooterConfig
默认值： { prev: 'Previous', next: 'Next' }

文档页面底部"上一篇/下一篇"的文本配置。

export default defineConfig({
  themeConfig: {
    docFooter: {
      prev: '上一页',
      next: '下一页'
    }
  }
})

最后更新

lastUpdated

类型： LastUpdatedConfig
默认值： { text: 'Last updated' }

最后更新时间显示配置。需同时启用站点级 lastUpdated: true。

export default defineConfig({
  lastUpdated: true,
  themeConfig: {
    lastUpdated: {
      text: '最后更新于',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'short'
      }
    }
  }
})

LastUpdatedConfig 字段详解：

字段	类型	默认值	说明
`text`	`string`	`'Last updated'`	前缀文本
`formatOptions`	`Intl.DateTimeFormatOptions`	—	日期格式化选项

常用 formatOptions：

配置	效果
`{ dateStyle: 'full' }`	2026 年 5 月 9 日星期六
`{ dateStyle: 'long' }`	2026 年 5 月 9 日
`{ dateStyle: 'medium' }`	2026/5/9
`{ dateStyle: 'short' }`	26/5/9
`{ dateStyle: 'full', timeStyle: 'short' }`	2026 年 5 月 9 日星期六 14:30

本地化文本

以下配置用于自定义 UI 中各处显示的文本：

字段	类型	默认值	说明
`returnToTopLabel`	`string`	`'Return to top'`	返回顶部按钮文本
`sidebarMenuLabel`	`string`	`'Menu'`	移动端侧边栏菜单文本
`darkModeSwitchLabel`	`string`	`'Appearance'`	深色模式切换按钮文本
`lightModeSwitchTitle`	`string`	`'Light'`	浅色模式选项标题
`darkModeSwitchTitle`	`string`	`'Dark'`	深色模式选项标题
`skipToContentLabel`	`string`	`'Skip to content'`	跳转到内容链接文本

export default defineConfig({
  themeConfig: {
    returnToTopLabel: '返回顶部',
    sidebarMenuLabel: '菜单',
    darkModeSwitchLabel: '主题',
    lightModeSwitchTitle: '浅色',
    darkModeSwitchTitle: '深色',
    skipToContentLabel: '跳转到正文'
  }
})

其他配置

externalLinkIcon

类型： boolean
默认值： false

是否在外部链接后显示图标。

export default defineConfig({
  themeConfig: {
    externalLinkIcon: true  // 外部链接显示 ↗ 图标
  }
})

notFound

类型： NotFoundConfig
默认值： 默认 404 页面

自定义 404 页面配置。

export default defineConfig({
  themeConfig: {
    notFound: {
      title: '页面未找到',
      quote: '看起来你访问了一个不存在的页面',
      linkLabel: '返回首页',
      linkText: '回到首页'
    }
  }
})

NotFoundConfig 字段详解：

字段	类型	默认值	说明
`title`	`string`	`'PAGE NOT FOUND'`	404 标题
`quote`	`string`	`'But if you don\'t change your direction...'`	引用文字
`linkLabel`	`string`	`'Take me home'`	链接标签
`linkText`	`string`	`'Take me home'`	链接文本
`code`	`string`	`'404'`	状态码

完整配置示例

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

export default defineConfig({
  title: '我的文档',
  description: '一个 VitePress 站点',

  themeConfig: {
    // 基础配置
    logo: '/logo.svg',
    siteTitle: '我的文档',

    // 导航栏
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/reference/' },
      {
        text: '更多',
        items: [
          { text: '教程', link: '/tutorial/' },
          { text: '示例', link: '/examples/' }
        ]
      }
    ],

    // 多侧边栏
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ],
      '/reference/': [
        {
          text: 'API 参考',
          base: '/reference/',
          items: [
            { text: '运行时 API', link: 'runtime-api' },
            { text: '构建 API', link: 'build-api' }
          ]
        }
      ]
    },

    // 社交链接
    socialLinks: [
      { icon: 'github', link: 'https://github.com/...' }
    ],

    // 搜索
    search: {
      provider: 'local',
      options: {
        translations: {
          button: { buttonText: '搜索文档' }
        }
      }
    },

    // 编辑链接
    editLink: {
      pattern: 'https://github.com/.../edit/main/docs/:path',
      text: '编辑此页'
    },

    // 页脚
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026'
    },

    // 大纲
    outline: {
      level: [2, 3],
      label: '目录'
    },

    // 最后更新
    lastUpdated: {
      text: '最后更新',
      formatOptions: { dateStyle: 'full' }
    },

    // 本地化文本
    returnToTopLabel: '返回顶部',
    sidebarMenuLabel: '菜单',
    darkModeSwitchLabel: '主题',

    // 其他
    externalLinkIcon: true
  }
})

参考链接

站点配置 - 站点级配置
Frontmatter 配置 - 页面级配置
主题 API - 主题开发 API
构建 API - 构建 API 参考
VitePress 官方主题配置文档

主题配置 ​

快速参考 ​

基础配置 ​

logo ​

siteTitle ​

导航栏配置 ​

nav ​

单层链接 ​

下拉菜单 ​

嵌套下拉菜单 ​

带徽章的导航 ​

NavItem 类型详解 ​

activeMatch 示例 ​

侧边栏配置 ​

sidebar ​

单侧边栏 ​

多侧边栏 ​

SidebarItem 类型详解 ​

折叠分组 ​

使用 base 简化路径 ​

社交链接 ​

socialLinks ​

内置图标 ​

自定义 SVG 图标 ​

社交链接 + aria-label ​

搜索配置 ​

search ​

本地搜索 ​

本地搜索选项 ​

Algolia 搜索 ​

Algolia 选项详解 ​

编辑链接 ​

editLink ​

页脚配置 ​

footer ​

大纲配置 ​

outline ​

文档页脚 ​

docFooter ​

最后更新 ​

lastUpdated ​

本地化文本 ​

其他配置 ​

externalLinkIcon ​

notFound ​

完整配置示例 ​

参考链接 ​

📖 相关文章推荐

贡献者