共计 5280 个字符，预计需要花费 14 分钟才能阅读完成。
介绍
在之前为了搭建 VuePress 的文档，顺带制作了视频教程，如今准备再次搭建一个 VuePress 的项目，一看自己的视频竟然有五个小时，天呐，我只是需要过一遍而已，所以重新整理成文档吧，万一将来又要用呢……
当然，如果您觉得文字版不够直观，可以前往观看视频版：【☛ 视频地址 ☚】，当时录制完本地测试后觉得声音大小还可以，结果一套录完了才发现声音很小，所以推荐带上耳机。
VuePress 文档示例
环境准备
对于环境准备不怎么熟悉的还是推荐看 视频第一节 吧。
Windows
安装 cmder 解压完成后复制其路径地址，将其添加到环境变量。
使用 Win + R 键快速启动 cmder，若成功则添加环境变量成功。
安装 git 安装包一路 next 即可，在桌面上右键出现 git bash here 或命令行中输入 git –version 能够得到具体的版本信息则安装成功。
安装 nodejs 安装包同样一路 next 即可，在命令行输入 node -v，若得到具体版本信息则安装成功。
安装 yarn 安装完成后，在命令行输入 yarn –version，若得到具体版本信息则安装成功。
创建项目
创建项目可以分为两种形式：
远程仓库
# xxx 为你的远程仓库连接
git clone xxx
cd your_project_name
npm init -y
本地仓库
# xxx 为你的远程仓库连接
npm init your_project_name -y
cd your_project_name
git remote add origin xxx
安装 vuepress
# 全局安装
yarn global add vuepress@next # 或者：npm install -g vuepress@next
# 本地安装
yarn add -D vuepress@next # 或者：npm install -D vuepress@next
配置 package.json 脚本
如果你的文档不是在 docs 下，可以按照你的设置来：
{
“scripts”: {
“docs:dev”: “vuepress dev docs”,
“docs:build”: “vuepress build docs”
}
}
上面配置完后，可以进行测试：
yarn docs:dev # 或者：npm run docs:dev
若能在浏览器中正常访问，则表示安装成功。
Linux
Linux 配置与 Windows 所需一致，相信都用上 Linux 了，这点问题能够解决。
搭建及优化
1. 了解路由与配置导航
关于文件是如何渲染为对应的路由的：
文件的相对路径
页面路由地址
/README.md
/
/guide/README.md
/guide/
/config.md
/config.html
了解了这个基本的概念后，就可以去配置对应的导航了。具体的导航栏配置介绍可以看 官方文档，看不懂可以去看我的 视频。
在实践后发现，若将所有内容放置在 docs/.vuepress/config.js 下将会很臃肿，难以阅读与维护，推荐将其分离开，在根目录下新建一个 config 文件夹：
// docs/.vuepress/config.js
const navConf = require(‘../../config/navConf.js’);
module.exports = {
themeConfig: {
nav: navConf
},
}
举个例子：
// config/navConf.js
module.exports = [
{text: ‘Home’, link: ‘/’},
{text: ‘Guide’, link: ‘/guide/’},
{text: ‘ 基础 ’, items: [
{text: ‘Algorithm’, link: ‘/base/algorithm/’},
{text: ‘Interview’, link: ‘/base/interview/’},
{text: ‘Clean’, link: ‘/base/clean/’},
{text: ‘Git’, link: ‘/base/git/’},
]},
{
text: ‘ 开发 ’,
items: [
{text: ‘FrontEnd’, items: [
{text: ‘JavaScript’, link: ‘/FrontEnd/javascript/’},
{text: ‘CSS’, link: ‘/FrontEnd/css/’},
{text: ‘Webpack’, link: ‘/FrontEnd/webpack/’},
{text: ‘Nodejs’, link: ‘/FrontEnd/nodejs/’},
]},
{text: ‘BackEnd’, items: [
{text: ‘Koa’, link: ‘/BackEnd/koa/’},
{text: ‘MongoDB’, link: ‘/BackEnd/mongodb/’},
{text: ‘Nginx’, link: ‘/BackEnd/nginx/’},
] },
]
}
];
2. 配置侧边栏
侧边栏比导航栏要更为繁琐一些。具体的导航栏配置介绍可以看 官方文档。
首先在 docs 文件夹下新建你需要的目录及文件：
OS
├── centos
│ ├── 01-add-user.md
│ ├── 02-login-with-rsa-key.md
│ ├── 03-upload-file-to-server.md
│ └── README.md
├── manjaro
│ ├── 01-solve-problems-with-manjaro.md
│ └── README.md
└── windows
└── README.md
配置 config 文件，当文章很多的情况下，还集中在 config 文件中，那就得炸了：
// docs/.vuepress/config.js
const sidebarConf = require(‘../../config/sidebarConf/index.js’);
module.exports = {
themeConfig: {
sidebar: sidebarConf
},
}
文章需要进行分类，所以会分成更多的子文件，通过 index.js 进行管理：
# config/sidebarConf
sidebarConf
├── Base
│ ├── algorithm
│ │ └── index.js
│ ├── clean
│ │ └── index.js
│ ├── git
│ │ └── index.js
│ └── interview
│ └── index.js
├── Guide
│ └── index.js
├── index.js
└── OS
├── centos
│ └── index.js
├── manjaro
│ └── index.js
└── windows
└── index.js
// config/sidebarConf/index.js
// 介绍
const guide = require(‘./Guide/index.js’);
// 基础
const git = require(‘./Base/git/index.js’);
const interview = require(‘./Base/interview/index.js’);
const algorithm = require(‘./Base/algorithm/index.js’);
const clean = require(‘./Base/clean/index.js’);
// 操作系统
const windows = require(‘./OS/windows/index.js’);
const manjaro = require(‘./OS/manjaro/index.js’);
const centos = require(‘./OS/centos/index.js’);
/**
* 侧边栏的配置
* 当路由深度越深时应当排序在更前方
* 示例: /frontend 和 /frontend/css
*
* 应当将 /frontend/css 写在更上方
*/
module.exports = {
// 指南 Guide
‘/guide/’: guide,
// 基础 Base
‘/Base/git/’: git,
‘/Base/interview/’: interview,
‘/Base/clean/’: clean,
‘/Base/algorithm/’: algorithm,
// 操作系统 OS
‘/OS/manjaro/’: manjaro,
‘/OS/windows/’: windows,
‘/OS/centos/’: centos,
// 根目录下的 sidebar, 对于所有未匹配到的都会应用该 sidebar
// ‘/’: [”] // 此处选择禁用
};
以 CentOS 举个例子：
// config/sidebarConf/OS/centos/index.js
const utils = require(‘../../../../utils/index.js’);
const children = [”,’01-add-user’,’02-login-with-rsa-key’,’03-upload-file-to-server’];
module.exports = [
utils.genSidebar(‘CentOS’, children, false),
];
genSidebar 函数：
const utils = {
genSidebar: function (title, children = [”], collapsable = true, sidebarDepth = 1) {
return {
title,
collapsable,
sidebarDepth,
children
}
}
};
module.exports = utils;
3. SEO 配置
基本配置可以帮助我们做好网站的 SEO，更容易被搜索到。具体的基本配置介绍可以看 官方文档。
// docs/.vuepress/config.js
module.exports = {
title: ‘ 飞跃高山与大洋的鱼 ’,
description: ‘ 飞跃高山与大洋的鱼的文档, vuepress 文档 ’,
}
4. 更新时间与静态资源
更新时间，如果按照文档进行配置的话时间格式是非中文的风格，解决很简单：
// 添加多语言，改为国内即可
module.exports = {
locales: {
‘/’: {
lang: ‘zh-CN’,
}
},
themeConfig: {
lastUpdated: ‘ 上次更新 ’,
},
}
所有的静态资源都需要放置在 .vuepress/public 目录下，你也可以为它们建立分类文件夹（这里不好的效果是在预览本地的 Markdown 文件时无法看到图片）：
public
├── apple-touch-icon.png
├── app.png
├── base
│ └── interview
│ └── 1468042984788341.png
├── favicon-32×32.png
├── favicon.ico
├── FrontEnd
│ └── javascript
│ ├── es6_20190112123602.png
│ └── es6_20190112124206.png
├── manifest.json
5. 部署到 github 并关联到自定义域名
具体的部署介绍可以看 官方文档。
之前做视频的时候还没有 Travis CI 的使用说明，刚刚看的时候发现有了，昨天花了好久来硬啃 Travis 官网，血亏……
这边我发布到的是 docs.shanyuhai.top，所以 base 属性默认为空即可；若是发布到 docs.shanyuhai.top/docs 则 base 属性为 docs。
deploy.sh 文件示例：
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
echo ‘docs.shanyuhai.top’ > CNAME
git init
git add -A
git commit -m ‘deploy’
# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:shanyuhai123/documents.git master:gh-pages
cd –
6. 添加 Git 仓库和编辑链接
参考文档及视频同上：
// docs/.vuepress/config.js
module.exports = {
themeConfig: {
// 你的 Git 项目地址，添加后会在导航栏的最后追加
repo: ‘shanyuhai123/documents’,
// 启用编辑
editLinks: true,
// 编辑按钮的 Text
editLinkText: ‘ 编辑文档！’,
// 编辑文档的所在目录
docsDir: ‘docs’,
// 假如文档放在一个特定的分支下：
// docsBranch: ‘master’,
},
}
7. 域名解析
关于域名解析详情可以去看我的 视频（第五个视频中的解析方式存在问题）。
解析方式需要改为 CNAME 的形式：
最后
为了方便阅读，所以将内容进行了划分，关于插件具体介绍的文档还在书写中，有时间可以先去看下 视频。
参考资料
VuePress 官网