一步步搭建 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-32x32.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 [email protected]: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 初始化及发布
- VuePress 插件系列
- VuePress 自动化