使用文档
这一页带你走一遍主题会怎样处理你的 markdown，从第一页到成品站点。 配置参考 是查阅手册，这一页是走查。
1. 最短的路径
// docs/.vuepress/config.js
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from 'vuepress'
import { githubTheme } from 'vuepress-theme-github'
export default defineUserConfig({
bundler: viteBundler(),
title: '我的项目',
theme: githubTheme(),
})docs/ 下的一切现在都是带着仓库外壳的页面。
2. 一个落地页
docs/README.md 带上 home: true 时渲染为首页视图：
---
home: true
hero:
name: 我的项目
text: 只做好一件事
tagline: 并且在一个像仓库一样的文档站里告诉你怎么做。
image: /images/logo.png
actions:
- text: 开始使用
link: /guide/getting-started.md
theme: brand
- text: GitHub
link: https://github.com/you/your-repo
theme: alt
features:
- title: 快
details: 纯静态产物，无运行时。
- title: 小
details: 一份样式表，一个脚本。
---Hero 的字段全部可选；actions 也可以写在顶层。frontmatter 下面的 markdown 正文会 渲染在 Hero 之下，features 再变成下方的网格。
3. 文档页面
写 markdown 即可。标题会变成：
- 右侧的页内目录
- 锚点目标（
#installation） - 上一页/下一页链路（配置了侧边栏时）
---
title: 安装
sidebarDepth: 3 # 页内目录的深度
toc: false # 本页隐藏页内目录
sidebar: false # 本页隐藏侧边栏
pageNav: false # 本页隐藏上一页/下一页
---4. 侧边栏
一个数组应用于所有页面；对象则把路径前缀映射到各自的数组，最长匹配前缀生效。
sidebar: {
'/guide/': [
{ text: '介绍', children: ['/guide/README.md', '/guide/install.md'] },
{ text: '参考', children: ['/guide/configuration.md'] },
],
}分组可折叠，当前页所在的分组会自动展开。条目可以是纯字符串，也可以是带 text、 link、icon、children 的对象。
5. 博客
把文章放在 posts/ 下：
---
title: 你好
date: 2026-03-01
tags: [release, notes]
excerpt: 用于列表的一段摘要。
---主题随后会生成列表页（/blog/）、每个标签一个页面（/blog/tags/release/）、标签 总览与归档。不需要你写任何页面文件。分页、置顶与按 locale 的博客见 博客。
6. 在 markdown 里用组件
下面这些全部全局注册：在任何 markdown 文件里直接用，无需 import。
<WNote type="warning" title="注意">迁移前先备份。</WNote>
<WCardList :cols="2">
<WCard title="文档" link="/guide/">阅读指南。</WCard>
<WCard title="博客" link="/blog/">发布记录。</WCard>
</WCardList>
<WSteps>
<WStep title="安装">加上依赖。</WStep>
<WStep title="配置">把主题指向 <code v-pre>githubTheme</code>。</WStep>
</WSteps>
状态：<Badge type="success">stable</Badge>完整清单见组件。
7. 导航
navbar: [
{ text: '指南', link: '/guide/' },
{
text: '组件',
children: [
{ text: '总览', link: '/components/' },
{ text: '容器', link: '/components/containers.md' },
],
},
{ text: '博客', link: '/blog/' },
]每个条目一层 children，渲染为下拉。链接可以写成 /guide/、/guide/install.md 或 /guide/README.md —— 三者解析到同一个路由。
8. 配色
导航栏上的按钮切换浅色与深色。这个选择：
- 在读者做出选择之前跟随操作系统
- 存在
localStorage的github-theme-color-scheme键下 - 由一段内联脚本在首次绘制前应用，所以不会闪
logoDark 可以换一个在深色背景上好看的 logo。
9. 搜索
默认开启、完全本地，索引每个页面渲染出来的文本。见搜索。
10. 多语言
locale 要声明两次 —— 一次给 VuePress，一次给主题 —— 每个 locale 就拥有自己的导航栏、 博客路由与 UI 文案。见多语言。
11. 发布
npm ci
npm run docs:build # → docs/.vuepress/dist把产物部署到任意静态托管即可。构建镜像设为 Node 22.18 或更新。逐宿主的说明见 部署。