前言： 你是不是很多次看到第三方UI库的文档比如vue官方文档、element UI文档，以及很多自己搭建的博客，风格都是类似的。那你是不是也想搭建一套属于自己的博客，来自己写一份文档呢？看完这篇文章，我相信你一定会对这个有一定程度的理解，下面就跟着笔者一步一步搭建属于自己的第一个在线博客，编写属于你的第一个在线技术文档，并且实现自动打包部署。
目标
我们先来看一下我们看完这篇文章后，能够达到一个什么样的效果。首先先贴一张图看一下vue官方文档的实现效果：
再来看一下element ui的实现效果：
观察两张图我们可以发现，网页分为三个部分，顶部、侧边栏、内容区。其中内容区域可以看出来是使用的是Markdown进行编写的，并且能够支持vue语法，并且显示代码块。
我们选择vuepress来进行实现，由于我们考虑到学习的成本，我们就暂时先将最终的网页发布到github提供的免费静态网页服务中，也就是github pages，下面开始实现。
vuepress下载安装及其使用
创建一个文件夹，通过vscode打开，新建终端并且全局安装vuepress：
# 全局安装
npm install -g vuepress
在文件夹根目录创建package.json用来安装我们的依赖，以及创建npm脚本。 接着继续在项目根目录创建docs文件夹用来作为我们项目的主体文件夹。此时我们的项目结构如下：
此时先对package.json进行修改，写入以下json：
{
"name": "vuepress",
"version": "1.0.0",
"description": "练习vuepress文档编写",
"main": "index.js",
"author": "DGT",
"license": "MIT",
"private": false,
"devDependencies": {
"vuepress": "^1.9.9"
},
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs",
}
}
主要是对当前项目的基本信息的描述，这里就不过多介绍了。主要的是在scripts里面这里写了两个命令，docs:dev 以及docs:build,这里的dev作为在本地运行vuepress项目，build则是对本地项目进行打包。 接着在docs文件夹下创建一个.vuepress文件夹，注意vuepress前面有一个.
在docs文件夹下面创建一个guide目录用于存放我们md页面元素，并且现在随机写两个md文件用于测试。
在.vuepress文件夹下创建一个config.js作为我们vuepress项目的配置文件。
在docs文件夹下创建README.md文件作为我们的主md文件。
现在我们的目录结构如下：
至此、基本的项目结构已经好了，接下来开始对项目进行配置
编辑config.js:
module.exports = {
title: 'Hello VuePress',
description: 'Just playing around'
}
这里指定了当前项目的标题以及基本描述。 在项目根目录运行npm run docs:dev在依赖安装正确的情况下，我们能够在网页中看到一个初步的页面。
这样我们的第一个页面就跑起来了，接下来对配置文件进行编辑，丰富这个网页。
在config.js中添加以下配置：
themeConfig:{
sidebar: [
{
title:'plugins',
collapsable: false, //是否折叠
children:[
{
title:'去掉全部console测试',
path:'/guide/1.md',
}
],
},
{
title:'loaders',
collapsable: false, //是否展开
children:[
{
title:'生成打包信息',
path:'/guide/2.md',
}
],
},
]
}
这里添加了两个侧边栏，打开页面发现页面上没有更新，这里需要在package.json添加配置，激活vuepress的热更新。 如下：
"scripts": {
"docs:dev": "vuepress dev docs --temp .temp",
"docs:build": "vuepress build docs",
}
这样就可以同步热更新了。这样一个简单的静态网站就已经做好了。具体的其他配置可以参考vuepress官方文档
打包部署
首先需要在github上自己创建一个空的仓库。
修改vuepress项目的config配置文件，添加base配置（重要，一定要正确）：
module.exports = {
title: 'Hello VuePress',
description: 'Just playing around',
base:'/studyspace/', // 设置为github仓库地址，用来部署到github pages
themeConfig:{
sidebar: [
{
title:'plugins',
collapsable: false, //是否折叠
children:[
{
title:'去掉全部console测试2',
path:'/guide/1.md',
}
],
},
{
title:'loaders',
collapsable: false, //是否展开
children:[
{
title:'生成打包信息',
path:'/guide/2.md',
}
],
},
]
}
}
在项目根目录下运行
npm run docs:build
导航进入到dist文件
cd docs/.vuepress/dist
在终端依次执行
git init
git add -A
git commit -m 'deploy'
最后将打包后的dist代码推送到github之前创建好的仓库中。
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
其中的/替换为你自己仓库的用户名以及仓库名。例如： 我的仓库地址是：DGT182****2792/studyspace 替换后的命令是：
git push -f git@github.com:DGT182****2792/studyspace.git master:gh-pages
执行完毕后，打开github仓库找到setting设置下的pages配置：点击GitHub Pages 即可知道当前静态资源的地址。这样就实现了打包及部署。
为了方便实现自动化部署，将以上打包部署的流程编写成shell脚本，在项目的根目录下创建deploy.sh文件。编辑：
# 创建脚本用于自动部署到github仓库上面、并实现自动更新静态网页
# 构建打包
vuepress build docs
# 导航到构建输出目录
cd docs/.vuepress/dist
git init
git add -A
git commit -m '更新'
# 推到你仓库的的 gh-page 分支
# 将 <USERNAME>/<REPO> 替换为你的信息
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
然后修改package.json文件，添加运行脚本的命令：
"scripts": {
"docs:dev": "vuepress dev docs --temp .temp",
"docs:build": "vuepress build docs",
"docs:deploy": "vuepress build docs && bash deploy.sh"
}
在终端执行npm run docs:deploy命令后，即可实现自动打包部署。 注意：如果使用的vscode编辑器的时候执行词条命令可能会报错，识别不了”bash“。这里有两种方案，一是新建终端的时候选择PoweShell终端。二是直接导航到这个目录打开git bash然后再执行命令。（由于直接在vscode终端中是不能直接运行sh脚本的、在linux环境中则不会出现这个问题）。
至此我们的目标基本实现了，在下一篇文章中我们将继续深入优化我们的文档项目，并且实现在vuepress中使用vue组件。
