介绍
在之前为了搭建 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 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
的形式:
最后
为了方便阅读,所以将内容进行了划分: