vuepress搭建网站
使用本项目
克隆到本地
git clone https://github.com/liyao52033/vuepress-default.git
yarn install
脚本说明
"scripts": {
"docs:dev": "vuepress dev docs", //启动项目
"docs:build": "vuepress build docs", // 打包项目
"docs:nav": "vuepress nav docs -f" , // 生成导航栏与侧边栏
"deploy": "./docs/.vuepress/deploy.sh", //部署到github.io
"push": "./docs/push.sh" //推送到github
},
启动项目
yarn run docs:dev
在docs构建目录如下
docs
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│ ├─ test
│ ├─ ├─ README.md
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar/
├─ README.md
├─ three.md
└─ four.md
文件夹可以嵌套，但每个文件夹都必须有README目录，不然会报404
导航栏与侧边栏
voding主题已经提供结构化侧边栏，也内置了自动生成侧边栏插件，两者选一即可
- 若使用自动生成侧边栏插件，执行以下命令，将生成的nav.js在.vuppress/config.js引入即可自动生成侧边栏, 更多内容见官网
// 生成nav.js
yarn run docs:nav
//使用插件并引入nav.js .vuepress/config.js
const nav = require("./nav.js");
module.exports = {
plugins: [
["vuepress-plugin-auto-sidebar",{
sidebarDepth: 2,
collapse: {
open: true,
},
}],
]
themeConfig: {
nav
}
}
- 若使用vdoing主题侧边栏，导航栏只需写与.vuepress同层的一级目录，link写该文件夹内任意md文件frontmatter的permalink,格式如下，更多内容见官网
// config.js
module.exports = {
themeConfig: {
nav: [
// 没有二级导航时可以直接添加
{text: '目录页', link: '/web/'},
// 有二级导航时
{text: '页面',
/** 目录页， vdoing主题新增的配置项，有二级导航时，可以点击一级导航跳到目录页，
依赖于结构化的侧边栏数据，就是说你需要在config.js配置 sidebar: 'structuring' 或 sidebar: { mode: 'structuring', collapsable: false} 才能实现目录页数据的获取。**/
link: '/ui/',
items: [
{text: 'HTML', link: '/pages/11/'},
{text: 'CSS', link: '/pages/22/'},
]
},
]
}
}
部署，此处只部署到 USERNAME.github.io,其他情况见官网
修改deploy.sh的仓库路径
# 如果发布到 https://<USERNAME>.github.io
git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git main
部署
yarn run deploy
二. 从零到一根据官网搭建
安装
yarn add -D vuepress
注意
如果你的现有项目依赖了 webpack 3.x，我们推荐使用 Yarn (opens new window)而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树,导致项目无法启动
在 package.json 中添加脚本
这一步骤是可选的，但我们推荐你完成它。在下文中，我们会默认这些 scripts 已经被添加。
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
在本地启动服务器
yarn docs:dev
目录结构
VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：
.
├── docs
│ ├── .vuepress (可选的)
│ │ ├── components (可选的)
│ │ ├── theme (可选的)
│ │ │ └── Layout.vue
│ │ ├── public (可选的)
│ │ ├── styles (可选的)
│ │ │ ├── index.styl
│ │ │ └── palette.styl
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html
│ │ │ └── ssr.html
│ │ ├── config.js (可选的)
│ │ └── enhanceApp.js (可选的)
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md
│
└── package.json
注意
请留意目录名的大写。
-
docs/.vuepress: 用于存放全局的配置、组件、静态资源等。 -
docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。 -
docs/.vuepress/theme: 用于存放本地主题。 -
docs/.vuepress/styles: 用于存放样式相关的文件。 -
docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。 -
docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。 -
docs/.vuepress/public: 静态资源目录。 -
docs/.vuepress/templates: 存储 HTML 模板文件。 -
docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。 -
docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。 -
docs/.vuepress/config.js: 配置文件的入口文件，也可以是YML或toml。 -
docs/.vuepress/enhanceApp.js: 客户端应用的增强。默认的页面路由
此处我们把
docs目录作为targetDir（参考 命令行接口），下面所有的“文件的相对路径”都是相对于docs目录的。在项目根目录下的package.json中添加scripts：{ "scripts": { "dev": "vuepress dev docs", "build": "vuepress build docs" } }对于上述的目录结构，默认页面路由地址如下：
文件的相对路径 页面路由地址 /README.md//guide/README.md/guide//config.md/config.html
默认的主题提供了一个首页（Homepage）的布局 (用于 这个网站的主页)。想要使用它，需要在你的根级 README.md 的 YAML front matter 指定 home: true。
导航栏与侧边栏配置
用Vuepress Plugin Auto Sidebar自动生成插件，详细文档
安装
yarn add vuepress-plugin-auto-sidebar -D
使用
Attention, do not put
pluginsin the themeConfig
module.exports = {
plugins: [
["vuepress-plugin-auto-sidebar", {
sidebarDepth: 2,
collapse: {
open: true,
},
}]
]
}
快速生成简单的导航栏
-
添加脚本到
package.json中{ "scripts": { "docs:nav": "vuepress nav docs" } } -
执行命令
yarn run docs:nav
它将会在 .vuepress 文件夹下生成 nav.js 文件，每次新增文件夹都要执行一次该命令重新生成路由
-
引入生成的 nav 文件
const nav = require("./nav.js"); module.exports = { plugins: { "vuepress-plugin-auto-sidebar": {} }, themeConfig: { nav } }
专注写作
在docs目录下存放写的文章即可，目录如下
docs
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar/
├─ README.md
├─ three.md
└─ four.md
参考文章
最后更新于 2026-02-18 18:24