团队技术文档构建利器vuepress上手实践
Write By CS逍遥剑仙
我的主页: csxiaoyao.com
GitHub: github.com/csxiaoyaojianxian
Email: sunjianfeng@csxiaoyao.com
QQ: 1724338257
最近在尝试一些项目技术文档搭建的工具，看到网上很多人推荐 gitbook，使用后总体感觉良好。无意中发现一款 Vue 驱动的静态站点生成工具 vuepress，看到官网和demo后立即被它的简约灵活所吸引。一个 vuepress 网站是一个由 Vue、Vue Router 和 Webpack 驱动的单页应用。在构建时，创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。
本文做一个上手实践总结。如果正有搭建技术文档的需求，而且熟悉 vue 生态，相信我，选择 vuepress 一定不会后悔。官方文档地址：https://vuepress.vuejs.org，vue 生态一大优势在于中文文档，vuepress 也不例外，中文文档一样靠谱：https://www.vuepress.cn，官方文档十分详细，本文也不再过多搬运，主要讲下自己的实践。
1. 环境搭建
跟随 vuepress 文档操作一遍，非常顺畅，轻轻松松搭好。
yarn global add vuepress # 创建一个 markdown 文件，仅包含一个标题 > echo '# Hello VuePress' > README.md
编写文档，类似 webpack 中的 devServer，在本地启动一个服务器，浏览器访问 localhost:8080 进行访问。
# 开始编写文档 > vuepress dev
编写完文档需要打包构建后才能部署，文件在 ./vuepress/dist 目录下，可以通过配置 .vuepress/config.js 中的 dest 字段修改。
# 构建 vuepress build
如果是已经有项目，只是想在该项目中管理文档，则应该将 vuepress 安装为本地依赖，具体可以参考官方文档。
2. 目录结构
项目创建完后，最简的目录结构如下：
├─ docs │ ├─ README.md │ └─ .vuepress │ └─ config.js └─ package.json
官方推荐的完整目录结构如下：
├── docs │ ├── .vuepress (可选的) 用于存放全局的配置、组件、静态资源等 │ │ ├── components (可选的) Vue组件将会被自动注册为全局组件 │ │ ├── theme (可选的) 用于存放本地主题 │ │ │ └── Layout.vue │ │ ├── public (可选的) 静态资源目录 │ │ ├── styles (可选的) 用户存放样式相关文件 │ │ │ ├── index.styl 将会被自动应用的全局样式文件，会生成在最终的css文件结尾，具有比默认样更高级的优先级 │ │ │ └── palette.styl 用于重写默认样式常量，或者设置新的stylus颜色常量 │ │ ├── templates (可选的, 谨慎配置) 存储HTML模板文件 │ │ │ ├── dev.html │ │ │ └── ssr.html │ │ ├── config.js (可选的) 配置文件的入口文件 │ │ └── enhanceApp.js (可选的) 客户端应用的增强 │ │ │ ├── README.md │ ├── guide │ │ └── README.md │ └── config.md │ └── package.json
其中，docs 是项目根目录，名称可以自定义，.vuepress/config.js 是使用频率最高的配置文件，一般来说，实际的文档文件会放在根目录下，通过路由获取。
3. 参数配置
vuepress 提供了两类配置：
- 配置文件，如
.vuepress/config.js，需要导出一个js对象，一般用于进行全局配置 YAML front matter，配置在md文件头部，其后的内容才作为文档内容被渲染，一般用于针对当前文档的配置
3.1 主题配置
新建完后用户默认看到的页面是非常简陋的，只有一个包含搜索框的 head，vuepress 的强大之处在于可以灵活地进行主题配置，完成配置后一个丰富的技术文档页就构建好了，下面罗列常用的配置项及其功能，具体配置内容参考官方文档。
3.1.1 主页(homepage)
默认主题提供了一个首页（Homepage）布局，用于网站的主页 docs/README.md，使用 YAML front matter 配置。
3.1.2 导航栏(navbar)
themeConfig.nav 导航栏包括 左侧页面标题、搜索框、导航栏链接、多语言支持、仓库链接，支持下拉分组菜单，还支持在全局或单页面中禁用。
3.1.3 侧边栏(sidebar)
themeConfig.sidebar 侧边栏一般用于文档的目录索引，可以直接在 config.js 中配置链接数组，也在页面中配置 sidebar:auto 自动生成侧边栏目录，但是自动生成只能生成当前页。侧边栏还支持以下更加细节的设置：
- 设置嵌套层数
- 是否展开所有
- 标题链接是否激活(禁用可以懒加载提升性能)
- 分组
- 侧边栏分页面定制
- 禁用
3.1.4 搜索框(search box)
themeConfig.search 支持禁用、修改搜索提示数量、启用 Algolia Search。
3.1.5 最近更新
themeConfig.lastUpdated 选项允许获取每个文件的最后一次 git 提交的 UNIX 时间戳（ms），并以合适的格式显示在每个页面的底部。
3.1.6 Service Worker
themeConfig.serviceWorker 选项允许进行 service worker 相关的配置。
3.1.7 上一页 / 下一页链接(prev / next links)
可以在每个页面设置上下页链接。
3.1.8 Git 仓库和编辑链接
themeConfig.repo 会在导航中生成 github 链接。
3.2 样式编辑
3.2.1 默认样式覆盖
如果希望修改默认样式，可以创建两个文件 .vuepress/styles/index.styl、 .vuepress/styles/palette.styl，index.styl 作为全局样式文件生成在最终的css文件结尾，具有比默认样式更高的优先级，palette.styl 用于重写默认样式常量，或者设置新的 stylus 颜色常量，如：
$accentColor = #3eaf7c $textColor = #2c3e50 $borderColor = #eaecef $codeBgColor = #282c34
3.2.2 自定义页面类
若需要为特定页面添加一个 CSS 类名，可以在该页面的 YAML front matter 中声明一个 pageClass：
--- pageClass: custom-page-class ---
index.styl 中可以使用对应的类名：
.theme-container.custom-page-class {
/* 页面特定的规则 */
}
4. markdown 扩展操作
4.1 Emoji
</pre> <h3 id="h3-7">4.2 目录</h3> <pre><code>[[toc]]
4.3 自定义容器
::: tip 注意： This is a tip ::: ::: warning This is a warning ::: ::: danger STOP This is a dangerous warning :::
4.4 在代码块中高亮显示行
``` js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
4.5 导入代码片段
<<< @/public/test.js{2}
5. 在 Markdown 中使用 Vue
.vuepress/components 中的所有 *.vue 文件都会自动注册为全局异步组件，如：
.
└─ .vuepress
└─ components
├─ demo.vue
└─ Foo
└─ Bar.vue
可以直接在所有 markdown 文件中使用这些组件。
<demo/> <Foo-Bar/>
6. 自定义主题
创建 .vuepress/theme 目录和 Layout.vue 文件，详见文档。
7. GitHub Pages 部署
发布 GitHub Pages 需要在 .vuepress/config.js 中设置正确的 base。例如发布到 https://<USERNAME>.github.io/，base 默认即是"/"，如果打算发布到 https://<USERNAME>.github.io/<REPO>/（即仓库在 https://github.com/<USERNAME>/<REPO>），需要设置 base 为 "/<REPO>/"。
module.exports = {
base: '/test/'
}
可以在项目中创建 deploy.sh 文件，方便在持续集成的设置中在每次 push 代码时自动运行脚本。
#!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 npm run docs:build # 进入生成的文件夹 cd docs/.vuepress/dist # 如果是发布到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 如果发布到 https://<USERNAME>.github.io # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master # 如果发布到 https://<USERNAME>.github.io/<REPO> # git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages cd -
设置package.json
{
"script":{
"deploy": "bash deploy.sh",
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
运行脚本推送更新到 github 上
npm run deploy
8. 附录：config.js 详细配置 demo
module.exports = {
base: '/', // 用于部署时的子路径
title: 'csxiaoyao.com', // 网站的标题
description: 'luban document, created by victorsun', // 网站描述，HTML中表现为一个 <meta> 标签
head: [ // head 中额外标签
// ['link', { rel: 'icon', href: '/logo.png' }]
],
host: '0.0.0.0', // dev 服务器的主机
port: 2048, // dev 服务器的端口
dest: './dist', // 指定 vuepress build 的输出目录
evergreen: false, // 忽略浏览器兼容性
markdown: {
lineNumbers: true, // 代码块的左侧显示行号
externalLinks: { target: '_blank', rel: 'noopener noreferrer' }, // 键和值对将被添加到指向外部链接的 <a> 标签，默认选项将在新窗口中打开外部链接
anchor: { permalink: true, permalinkBefore: true, permalinkSymbol: '#' }, // 锚点配置
toc: { includeLevel: [1, 2, 3] }, // [[toc]]目录
config: md => { // 插件
// md.set({ breaks: true })
// md.use(require('markdown-it-xxx'))
}
},
themeConfig: {
nav: [ // 导航栏
{
text: '主页',
link: '/'
}, {
text: '菜单',
items: [{
text: '普通菜单',
link: '/'
}, {
text: '分组菜单',
items: [{
text: 'test1',
link: '/test1'
}, {
text: 'test2',
link: '/test2'
}]
}]
}, {
text: '访问主页',
link: 'http://www.csxiaoyao.com'
}
],
// 侧边栏
sidebar: [
'/test1',
['/test1', '链接到test1'],
{
title: '链接到test2',
collapsable: false,
children: [
'/test1',
'/test2',
]
}
],
// 展开所有标题层级
displayAllHeaders: false,
// 激活标题链接
activeHeaderLinks: true, // false 可以提高性能
// 搜索
search: true,
searchMaxSuggestions: 10,
// 更新时间戳 git
lastUpdated: 'Last Updated', // string | boolean
// serviceWorker
serviceWorker: {
updatePopup: true, // 弹窗提示更新 Boolean | Object, 默认值是 undefined
// 如果设置为 true, 默认的文本配置将是:
updatePopup: {
message: "有内容更新",
buttonText: "更新"
}
},
// 假定 GitHub，也可以是一个完整的 GitLab URL
repo: 'csxiaoyaojianxian/JavaScriptStudy',
// 自定义项目仓库链接文字，默认根据 `themeConfig.repo` 中的 URL 来自动匹配是 "GitHub"/"GitLab"/"Bitbucket" 中的哪个，如果不设置时是 "Source"
repoLabel: '访问仓库',
// 以下为可选的 "Edit this page" 链接选项，如果你的文档和项目位于不同仓库：
docsRepo: 'vuejs/vuepress',
// 如果你的文档不在仓库的根目录下：
docsDir: 'docs',
// 如果你的文档在某个特定的分支（默认是 'master' 分支）：
docsBranch: 'master',
// 默认为 false，设置为 true 来启用
editLinks: true,
// 自定义编辑链接的文本。默认是 "Edit this page"
editLinkText: '修改此页'
}
}
