本篇内容技术比较简单，大神自动飘过
VuePress是vue框架下静态网站生成器，用于生成技术文档相当实用。结合部署到github的站点功能，用起来不要太爽。编辑内容使用Markdown编辑器，做开发的肯定是喜欢这个编辑器了。整体流程就是打好框架，在里面编辑md文件，vue自动预览更新。编辑完成之后，build成纯静态文件，然后上传到站点中去，样子看着还是很舒服的。
这里有个缺点，就是只能处理纯静态的内容，想要动态内容自行绕过。另外，这个模块目前属于开发的alpha阶段，功能接口都有可能重新调整。
本文指导从零开始搭建所有的vuepress安装，使用并部署到github站点上成功运行。最终效果请点击文章底部的阅读原文。
安装
注意，nodejs版本自己去找最新稳定版 直接上命令：
# 安装
npm install -g vuepress
# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md
# 开始写作
vuepress dev .
# 构建静态文件
vuepress build .
上面命令是直接在根目录里面搭建的静态内容。一般这种技术文档，除非专门技术，都是在子文件夹下面的。
# 将 VuePress 作为一个本地依赖安装
npm install -D vuepress
# 新建一个 docs 文件夹
mkdir docs
# 新建一个 markdown 文件
echo '# Hello VuePress!' > docs/README.md
# 开始写作
npx vuepress dev docs
官方指导再package.json的script里面添加一条快捷命令，感觉并没有降低多少要敲命令的成本，估计就是为了少计几个命令吧。
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
运行起来站点，然后就可以开始进行写作了，保存文件都是实时更新的。
npm run docs:dev
# 或者
vuepress dev docs
编写完成之后打包静态文件
npm run docs:build
# 或者
vuepress build docs
打包之后默认会放在 ** .vuepress/dist ** 文件夹下面，把里面的内容全部直接上传到任何的空间下面都可以运行。不过可能因为使用绝对路径的原因，直接运行index.html的话，里面的样式图片脚本都不运行的。
文件目录
这里对应的默认文件是 README.md ，类似index.html,index.jsp,index.php等等。引擎再打包的时候会把 README.md 解析成index.html。
.
├── docs
│ ├── .vuepress (可选的) # 用于存放全局的配置、组件、静态资源等。
│ │ ├── components (可选的) # 该目录中的 Vue 组件将会被自动注册为全局组件
│ │ ├── theme (可选的) #用于存放本地主题。
│ │ │ └── Layout.vue
│ │ ├── public (可选的) #静态资源目录
│ │ ├── styles (可选的) #用于存放样式相关的文件。
│ │ │ ├── index.styl #将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
│ │ │ └── palette.styl #用于重写默认颜色常量，或者设置新的的 stylus 颜色常量。
│ │ ├── templates (可选的, 谨慎配置) #存储 HTML 模板文件。
│ │ │ ├── dev.html #用于开发环境的 HTML 模板文件。
│ │ │ └── ssr.html #构建时基于 Vue SSR 的 HTML 模板文件。
│ │ ├── config.js (可选的) #配置文件的入口文件，也可以是 YML 或 toml。
│ │ └── enhanceApp.js (可选的) #客户端应用的增强。
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md
│
└── package.json
按照对应的目录结构，生成对应的路由，默认的 / 会解析 docs/README.md。而 /guide/ 会显示docs/guide/README.md的内容。/config.html 会显示 docs/config.md的内容。
固定链接
使用过wordpress的人员应该都知道在设置里面有个选项是固定连接。vuepress的部分也是一样的。wordpress里面关于这块儿的中文翻译是
WordPress让您能够为您的永久链接和存档建立自定义URL结构。自定义URL结构可以为您的链接提高美感、可用性和前向兼容性。
这样可以在连接里面进行拼接 年，月，日，文件名等。由于vuepress关于博客部分的设计还不完善，关于作者，id，分类，等等就没有办法很好的拼接进来。使用方法可以通过全局配置或者局部文件配置来实现。
// .vuepress/config.js进行全局配置
module.exports = {
permalink: '/:year/:month/:day/:slug'
}
# 或者在文件前方进行局部文件的配置
---
title: Hello World
permalink: /hello-world
---
Hello!
可以配置选项有
:year # 文章年份，4位
:month # 文章月份，2位，会自动补0
:i_month # 文章月份，不会自动补0
:day # 文章日，2位，会自动补0
:i_day # 文章日，2位，不会自动补0
:slug # 开启固定链接后的别名，英文。
:regular # vuepress默认的链接
不过呢，我自己没有试成功，没有花时间去详细研究啥原因。
全局配置
使用vuepress比较重要的部分就是设置配置文件了。由于默认的主题就挺好看的，自定义主题的事情再说了。
配置信息都包含在 docs/.vuepress/config.js 文件中，格式如下：
module.exports = {
permalink: '/:year/:month/:day/:slug', //固定链接的全局配置
markdown: { //markdown编辑器的配置
lineNumbers: true, //代码显示行号，默认 false
toc: { includeLevel: [1, 2] }, //显示目录的默认层级
},
title: 'Vue教程', //网站的标题，默认主题几个地方用到
description: 'Tingno记编写的VUE教程', //网站的描述
base:'/docs/', //要部署的根目录，不配置的话，都会到网站根目录下面
themeConfig: { //主题的配置信息
nav: [ //导航栏配置
{ text: '首页', link: '/' }, //没有子导航的，显示文字和链接
{ text: '基础', items: [ //有自导航的，就显示文字和子导航对象，下同
{ text: '入门', link: '/base/base' },
{ text: '常见文件', link: '/base/file' },
{ text: '组件化', link: '/base/package' },
{ text: 'ES6新特性', link: '/base/es6' },
]},
{ text: '核心', items: [
{ text: '路由Router', link: '/core/Route' },
{ text: '状态Vuex', link: '/core/Vuex' },
]},
{ text: '工具', items: [
{ text: 'git', link: '/tools/git' },
{ text: 'webpack', link: '/tools/webpack' },
]},
{ text: '博客', link: 'https://notes.tingno.com' }, //链接也可以是外部链接
],
sidebar: [ //配置边栏的链接，一个对象、一个数组都可以。也可以分组，分组配置找官方。
'/', //默认配置链接，名称会自动生成，首页或者文件第一个标题
['/base/base','入门'], //或者指定链接和显示标题
['/base/es6', 'ES6新特性'],
['/base/file', '常见文件'],
['/base/package', '组件化'],
{ //复杂的带子目录的对象
title: '核心', //显示名称
collapsable: false, //控制子目录是否可折叠，默认 true，下同
children: [
['/core/Route', '路由Router'],
['/core/Vuex', '状态Vuex']
]
},
{
title: '工具',
children: [
['/tools/git', '版本管理工具git'],
['/tools/webpack', 'webpack']
]
}
],
sidebarDepth:5,
displayAllHeaders: true, // 显示所有活动链接，默认值：false
activeHeaderLinks: false, // 关闭实时更新url的hash值，默认值：true
lastUpdated: 'Last Updated', // 显示最后更新时间
//帮助编辑
// 假定是 GitHub. 同时也可以是一个完整的 GitLab URL
repo: 'q5276/vuestudy',
// 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为
// "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
repoLabel: '查看源码',
// 以下为可选的编辑链接选项
// 假如你的文档仓库和项目本身不在一个仓库：
docsRepo: 'q5276/vuestudy',
// 假如文档不是放在仓库的根目录下：
docsDir: 'docs',
// 假如文档放在一个特定的分支下：
docsBranch: 'master',
// 默认是 false, 设置为 true 来启用
editLinks: true,
// 默认为 "Edit this page"
editLinkText: '帮助我们改善此页面！'
}
}
当然还有好多其他的配置信息，可以直接通读官方文档去了解。
局部配置
官方文档里面一直强调用 YAML front matter 来进行配置，由于孤陋寡闻，英文太烂，看的我一脸懵逼。后来了解，就是在你编辑文档的头部直接使用 两个 — 进行包围的配置信息，YAML也姑且理解为也是一种标记语言吧。格式就是一行一个配置，通过冒号: 进行配置名和配置值的设置。举例
---
editLink: false
---
# 下面是markdown的正文内容
所有在具体的文档里面放的 YAML标记都属于局部配置信息。配置解释为：
---
#默认主题中配置首页的配置信息
home: true #设置true就代表是首页了
actionText: 快速上手 → #中间有个按钮的文字
actionLink: /base/base #中间按钮的链接
features: # 下面内容直接对照下默认主题上显示的内容就知道了
- title: 方便理解
details: 总之是各种奇奇怪怪的帮助理解例子，懂就懂，不懂拉倒。
- title: VuePress驱动
details: 照着VuePress官方教程搭建的这个文档，至于内容，当然是把以前写的那些复制粘贴上来了。
- title: 高性能
details: VuePress最后会渲染成一个静态文件，你说高性能不性能。如果你打开的慢，只能说明站长比较穷，服务器太差。
footer: MIT Licensed | Copyright © 2018-present Evan You
#其他常用配置信息
navbar: false #禁用侧边栏
sidebarDepth: 2 #标题嵌套深度
sidebar: auto #自动生成侧边栏
prev: ./some-other-page #上一篇内容
next: false #下一篇内容，false是没有
editLink: false #禁止全局配置里面编辑文件部分
pageClass: custom-page-class #自定义类名
layout: SpecialLayout #自定义布局的组件名
---
Markdown 拓展
由于我平时编辑内容使用的是有道云笔记，所以罗列一些在有道云笔记的markdown文档里面没有的，而且感觉还挺有用的拓展。
- vuepress里面默认是会给所有的标题都加上锚链接，h1-h6，并且会根据标题来生成目录。
- 直接在内容中使用 [[toc]] 会生成自动目录。
- 代码高亮，在代码开始标记后进行“` js{4,6} 可以指定js代码行高亮。
VUE拓展
既然使用了vue引擎，vue特性当然也少不了。在md正文里面，可以直接使用 {{}} 进行一些处理，比如vue的模板语法
{{ 2 + 1 }}
<span v-for="i in 3">{{ i }} </span>
{{ $page }}
也可以使用 vue的组件语法，样式预处理器如scss、less，脚本样式，内置组件等等。不过由于初期使用，没有过多涉猎，不好瞎说。
Github站点部署
经过上面一大堆文件配置文件，安装文件摧残之后，进行文件打包生成静态文件，就可以进行站点发布了。当然你也可以自行购买空间、域名进行配置。配置好之后直接ftp把文件传上去就完事儿了。
这里用到的是Github里面的 Github Pages服务，可以放一些静态文件进行项目展示。打开翻了翻里面提供的一些模板，发现好多开源项目的文档介绍文件都是用的这个服务。
废话到这里。
第一步： 注册github账号，不赘述自行注册。
第二步： 新建库（New Repository），库名注意 <用户名>.github.io。其他选项默认，然后点击创建按钮 Create Repository
第三步： 根据提示，设置本地代码库与线上的库的绑定，上传代码。上传代码之前记得添加.gitignore文件，屏蔽一些无用的和敏感文件。
echo "# <用户名>.github.io" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin https://github.com/<用户名>/<用户名>.github.io.git
git push -u origin master
第四部： 配置github pages。在库详情中 设置settings > 选项options > GitHub Pages 部分选择资源。设置后就可以使用 <用户名>.github.io 进行访问了。也可以设置下面的自定义域名Custom domain，把自己的二级域名使用CNAME别名解析到 <用户名>.github.io 上去，看着更好看。我就是这么搞的。
第四步： 就是进一步内容更新了，将编辑将打包的部分持续上传上去了。
正常编辑过程中是保存即所得的，内容编辑结束了才需要打包上传的。 到这一步我自己的折腾成两个不相关的库，发现两个库来回跳转。官方提供了一个方便的部署脚本，属于比较干净的那种。我这里直接修改成适合自己理解的，比较笨的一个。上传的时候直接执行下面的脚本就完成了源码库打包，上传，复制打包好的文件到发布库，然后进行更新上传的操作。
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 上传源码github
git add -A
git commit -m 'deploy'
git push
# 复制站点文件
# 首先删除原来文件夹下的所有内容
rmdir --ignore-fail-on-non-empty G:/githubpages/docs
# 复制打包好的文件
cp -avx "G:\vue\SSR\docs\.vuepress\dist" G:/githubpages/docs
# 进入生成的文件夹
cd G:/githubpages/
# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME
git add -A
git commit -m 'deploy'
git push
# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
cd -
# 最后刹车一下，不然刷刷也不知道刷了点儿啥
read -p "Press any key to continue." var
文末
到这里，就做了一个跟vue官方长一样的文档管理站点了。效果请点击文末的阅读原文或者查看更多了解。通过里面点击查看源码也可以看到发布在github上的源码。内容基本上都是跟着官方文档一步一步下来的。
欢迎鲜花和板砖，都是天天向上的动力。
点击顶上的vue就是vuepress做的站了。
