本篇内容技术比较简单，大神自动飘过

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 }} 
{{ i }} 
{{ $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://.github.io
# git push -f git@github.com:/.github.io.git master
# 如果发布到 https://.github.io/
# git push -f git@github.com:/.git master:gh-pages
cd -
# 最后刹车一下，不然刷刷也不知道刷了点儿啥
read -p "Press any key to continue." var

文末

到这里，就做了一个跟vue官方长一样的文档管理站点了。效果请点击文末的阅读原文或者查看更多了解。通过里面点击查看源码也可以看到发布在github上的源码。内容基本上都是跟着官方文档一步一步下来的。

欢迎鲜花和板砖，都是天天向上的动力。

Vue进阶篇-VuePress文档管理安装及Github免费建站

安装