配置参考

所有选项都可以在顶层设置，并按 locale 覆盖。

站点选项

选项	类型	默认值	说明
`hostname`	`string`	`null`	站点域名。启用 SEO、sitemap 与 RSS
`logo`	`string`	`null`	导航栏 logo
`logoDark`	`string`	`null`	深色模式下的 logo
`repo`	`string`	`null`	仓库地址，用于仓库按钮与编辑链接
`docsDir`	`string`	`docs`	仓库内文档所在目录
`docsBranch`	`string`	`main`	文档所在分支
`locales`	`object`	`{}`	按 locale 的覆盖
`themePlugins`	`object`	`{}`	开关或配置内置插件

布局选项

选项	类型	默认值	说明
`navbar`	`array`	`[]`	导航链接，支持一层 `children`
`sidebar`	`array \| object`	`false`	侧边栏数组，或以路径前缀为键的映射
`sidebarExtra`	`array`	`[]`	追加在解析结果之后的侧边栏项
`sidebarDepth`	`number`	`2`	页内目录深度（`2`–`6`）
`notFound`	`string[]`	内置	404 页面显示的文字
`backToTop`	`boolean`	`true`	显示返回顶部按钮
`toggleColorMode`	`boolean`	`true`	显示配色切换按钮
`progressBar`	`boolean`	`true`	顶部阅读进度条
`numbered`	`boolean`	`true`	页内目录给嵌套标题编号
`codeBlockLanguage`	`boolean`	`true`	代码块语言标签与复制按钮
`drawerTrapFocus`	`boolean`	`true`	移动端抽屉锁定焦点
`footer`	`object`	`null`	站点页脚：`{ message, copyright }`
`author`	`object`	`null`	作者信息，见下方「作者选项」
`search`	`boolean \| object`	`true`	本地搜索，见搜索
`blog`	`object \| false`	见博客	博客选项，`false` 关闭
`numbered`	`boolean`	`true`	是否给页内目录的嵌套标题编号

文案选项

完整清单见多语言，这里只列常用的：

选项	类型	默认值	说明
`selectLanguageText`	`string`	`Languages`	语言下拉的文案
`tocTitle`	`string`	`On this page`	页内目录上方的标题
`paginationLabel`	`string`	`Pagination`	翻页区域的 landmark 名称
`breadcrumbLabel`	`string`	`Breadcrumb`	博客面包屑的名称
`codeBlockLabel`	`string`	`Copy code`	代码复制按钮的文案
`codeBlockCopied`	`string`	`Copied`	复制成功后的按钮文案
`noDatedPosts`	`string`	`No dated posts yet.`	归档中没有带日期文章时的提示
`archiveMonths`	`string[]`	英文 12 个月	归档视图的月份名
`skipToContent`	`string`	`Skip to content`	skip link 文案
`toggleSidebar`	`string`	`Toggle sidebar`	导航开关与移动端抽屉的文案
`sidebarLabel`	`string`	站点标题 + `navigation`	侧边栏 landmark 的可访问名称
`backToTop`	`string`	`Back to top`	返回顶部按钮文案
`siteNavLabel`	`string`	`Site navigation`	导航栏 landmark 的可访问名称
`pageNavLabel`	`string`	`Page navigation`	上一页/下一页 landmark 的可访问名称
`openRepoLabel`	`string`	`Open {host} repository`	仓库链接的可访问名称
`authorLabel`	`string`	`Author`	页脚里作者名称前面的标签
`blog.*`	`object`	见博客	博客各处的标题与文案
`blog.words`	`string`	`:words words`	阅读时间旁的字数文案；不设则不显示

作者选项

author 声明一次，全站页脚与首页即可复用；页脚永远用它生成作者区块，不需要逐页写组件。

字段	类型	默认值	说明
`name`	`string`	—	作者名称，必填
`avatar`	`string`	`''`	头像 URL，缺省时退化为名称首字
`description`	`string`	`''`	一句话简介
`links`	`array`	`[]`	联系方式，元素为 `{ name, link, icon? }`

links[].link 是绝对 URL 时渲染成外链；其它值只作为文本展示，所以 QQ 群号这类不是网址的条目不会变成死链。links[].icon 是可选的短标签。

theme: githubTheme({
  authorLabel: '作者',
  author: {
    name: '科技酱',
    avatar: 'https://avatars.githubusercontent.com/u/306192419?v=4',
    description: 'vuepress-theme-GitHub 的作者。',
    links: [
      { name: '作者网站', link: 'https://docs.asoe.cn' },
      { name: 'GitHub', link: 'https://github.com/techjiang/' },
      { name: '哔哩哔哩', link: 'https://space.bilibili.com/1768832152' },
      { name: 'QQ 群', link: '291974598' },
    ],
  },
})

单个页面想要独立排版时，直接用 WAuthor 组件。

页脚选项

选项	类型	默认值	说明
`editLink`	`boolean`	`true`	显示编辑链接
`editLinkText`	`string`	`Edit this page`	编辑链接文案
`editLinkPattern`	`string`	`null`	自定义 href 模板
`lastUpdated`	`boolean`	`true`	显示更新时间
`contributors`	`boolean`	`true`	显示贡献者头像

页内目录

右侧的目录由页面实际渲染出来的标题生成，所以它不会列出不存在的章节。

sidebarDepth 决定深度（2–6）。它总是从 h2 开始，因为 h1 是页面标题。
更深的标题会嵌套成树，折叠时仍保留在 DOM 中，所以每个条目都保留自己的锚点。
numbered: true（默认）会给嵌套标题加上大纲编号，GitHub 风格：1.1、1.2、2.1。已经以数字开头的标题不动，页面第一个标题也不动 —— 与 GitHub 的行为一致。
指针悬停或键盘聚焦在目录上时，高亮暂停跟随滚动 —— 否则点击深层条目时高亮会在脚下跳走。
页面 frontmatter 里写 toc: false 可隐藏本页的目录。

阅读体验

进度条、代码块的语言标签与复制按钮、阅读时间与字数，都在阅读体验里。三个开关：

theme: githubTheme({
  progressBar: false,
  numbered: false,
  codeBlockLanguage: false,
})

无障碍

主题已经处理好的部分：

skip link 是 Tab 能到达的第一个元素，回车把焦点移到 <main>
导航栏、侧边栏、页内目录、翻页区各有独立的 landmark 名称
移动端抽屉是 role="dialog" + aria-modal：打开时焦点移入、Tab 循环在内部、 Escape 关闭并把焦点还给开关按钮，关闭后解除页面滚动锁
配色切换按钮用 aria-pressed 暴露状态，图标与页面实际配色永远一致
代码块复制按钮有可读名称，键盘 Tab 到即显示
尊重 prefers-reduced-motion：所有动画与平滑滚动降级

自定义组件时请保持同样的习惯：读 window 的代码放进 onMounted，不要用「先渲染 false、挂载后再改成 true」的 ref —— 那会造成 hydration 不一致。

导航栏

条目要么是链接，要么是分组。分组会展开成下拉。

navbar: [
  { text: '指南', link: '/guide/' },
  {
    text: '组件',
    children: [
      { text: '总览', link: '/components/' },
      { text: '容器', link: '/components/containers.md' },
    ],
  },
]

侧边栏

数组应用于所有页面。对象把路径前缀映射到各自的数组，最长匹配前缀生效。

sidebar: {
  '/guide/': [
    { text: '介绍', children: ['/guide/README.md', '/guide/getting-started.md'] },
    { text: '参考', children: ['/guide/configuration.md'] },
  ],
}

侧边栏条目可以是纯字符串，也可以是带 text、link、children 的对象。分组可折叠，当前页所在的分组会自动展开。

Frontmatter

上面每个选项都可以按页面覆盖。

---
title: 自定义标题
sidebar: false
toc: false
pageNav: false
meta: false
editLink: false
lastUpdated: false
---

键	默认值	说明
`home`	`false`	渲染首页布局
`blogView`	`page`	博客视图：`blog`、`tag`、`tags`、`archives` 之一
`sidebar`	主题配置	本页的侧边栏配置，`false` 隐藏
`toc`	`true`	显示页内目录
`pageNav`	`true`	显示上一页/下一页
`meta`	`true`	显示页脚
`title`	取自 markdown	页面标题
`description`	`null`	标题下方的副标题

插件

themePlugins 用来开关内置行为插件，或透传选项。把某个键设为 false 即关闭。

键	默认值	插件
`activeHeaderLinks`	启用	`@vuepress/plugin-active-header-links`
`autoFrontmatter`	启用	`@vuepress/plugin-auto-frontmatter`
`backToTop`	启用	主题自带的返回顶部按钮（不再是插件，见下）
`catalog`	启用	`@vuepress/plugin-catalog`，已排除 posts 目录
`copyCode`	启用	`@vuepress/plugin-copy-code`
`feed`	有 hostname 时	`@vuepress/plugin-feed`
`git`	启用	`@vuepress/plugin-git`
`linksCheck`	启用	`@vuepress/plugin-links-check`
`mediumZoom`	启用	`@vuepress/plugin-medium-zoom`
`nprogress`	启用	`@vuepress/plugin-nprogress`
`prismjs`	启用	`@vuepress/plugin-prismjs`
`seo`	有 hostname 时	`@vuepress/plugin-seo`
`shiki`	启用	`@vuepress/plugin-shiki`
`sitemap`	有 hostname 时	`@vuepress/plugin-sitemap`

返回顶部按钮属于主题，不来自插件

主题自己渲染返回顶部按钮。早前它同时启用了 @vuepress/plugin-back-to-top，于是每个页面出现两个叠在一起的返回顶部控件，而插件那个不由本主题设计样式。插件已移除；themePlugins.backToTop: false 仍然有效，会关闭主题自己的按钮。

themePlugins: {
  shiki: { themes: { light: 'github-light', dark: 'github-dark' } },
  mediumZoom: false,
}

多语言

theme: githubTheme({
  navbar: [{ text: 'Guide', link: '/guide/' }],
  locales: {
    '/zh/': {
      navbar: [{ text: '指南', link: '/zh/guide/' }],
      sidebar: { '/zh/guide/': ['/zh/guide/README.md'] },
    },
  },
})

站点级 locales（title、description、lang）留在 VuePress 配置里；主题只读自己的 theme options。