一步步搭建 VuePress 及优化【初始化到发布】

介绍在之前为了搭建 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 xxxcd your_project_namenpm init -y本地仓库# xxx 为你的远程仓库连接npm init your_project_name -ycd your_project_namegit 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若能在浏览器中正常访问，则表示安装成功。LinuxLinux 配置与 Windows 所需一致，相信都用上 Linux 了，这点问题能够解决。搭建及优化1. 了解路由与配置导航关于文件是如何渲染为对应的路由的：文件的相对路径页面路由地址/README.md//guide/README.md/guide//config.md/config.html了解了这个基本的概念后，就可以去配置对应的导航了。具体的导航栏配置介绍可以看 官方文档，看不懂可以去看我的 视频 。在实践后发现，若将所有内容放置在 docs/.vuepress/config.js 下将会很臃肿，难以阅读与维护，推荐将其分离开，在根目录下新建一个 config 文件夹：// docs/.vuepress/config.jsconst navConf = require(’../../config/navConf.js’);module.exports = { themeConfig: { nav: navConf },}举个例子：// config/navConf.jsmodule.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.jsconst sidebarConf = require(’../../config/sidebarConf/index.js’);module.exports = { themeConfig: { sidebar: sidebarConf },}文章需要进行分类，所以会分成更多的子文件，通过 index.js 进行管理：# config/sidebarConfsidebarConf├── 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.jsconst 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.jsmodule.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.json5. 部署到 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’ > CNAMEgit initgit add -Agit commit -m ‘deploy’# 如果发布到 https://<USERNAME>.github.io/<REPO>git push -f git@github.com:shanyuhai123/documents.git master:gh-pagescd -6. 添加 Git 仓库和编辑链接参考文档及视频同上：// docs/.vuepress/config.jsmodule.exports = { themeConfig: { // 你的 Git 项目地址，添加后会在导航栏的最后追加 repo: ‘shanyuhai123/documents’, // 启用编辑 editLinks: true, // 编辑按钮的 Text editLinkText: ‘编辑文档！’, // 编辑文档的所在目录 docsDir: ‘docs’, // 假如文档放在一个特定的分支下： // docsBranch: ‘master’, },}7. 域名解析关于域名解析详情可以去看我的 视频 （第五个视频中的解析方式存在问题）。解析方式需要改为 CNAME 的形式：最后为了方便阅读，所以将内容进行了划分，关于插件具体介绍的文档还在书写中，有时间可以先去看下 视频。参考资料VuePress 官网