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

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

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里面关于这块儿的中文翻译是

这样可以在连接里面进行拼接 年，月，日，文件名等。由于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文档里面没有的，而且感觉还挺有用的拓展。

1. vuepress里面默认是会给所有的标题都加上锚链接，h1-h6，并且会根据标题来生成目录。
2. 直接在内容中使用 [[toc]] 会生成自动目录。
3. 代码高亮，在代码开始标记后进行``` 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和小程序集合的框架mpvue，回头研究下。

WordPress代码高亮免插件纯代码实现

WordPress代码高亮功能是一个比较常见的功能，很多朋友选择用插件实现这个功能，不过wp自学笔记还是倾向于纯代码实现代码高亮的功能。

其实在WordPress编辑器内是有插入代码的按钮的，如果你使用的是古腾堡编辑器，只需要点击添加添加区块，选择代码区块即可：

如果你使用的是经典编辑器，点击段落-预格式化也可以输入代码：

如果不喜欢使用预格式化，可以在WordPress经典编辑器添加新的插入代码按钮来实现添加代码，具体教程可以参考下面这篇文章。

接下来就是代码区域美化了，在主题css文件添加下面代码：

//CSS样式美化可以根据自己的主题风格调整pre {    font-size: 13px;    position: relative;    background: #141415;    color: #fff;    border-left: 5px solid #2c63ff;}.single-copy {    background: #2c63ff;    padding: 5px 10px;    font-size: 13px;    border-bottom-left-radius: 4px;    cursor: pointer;    position: absolute;    top: 0;    right: 0;    color: #fff;}

美化后的代码区域样式就变成下面这样效果了：

一个简易的代码高亮效果就完成了，不过有朋友问我右上角的意见复制效果是怎么实现的，这个就有点复杂了，需要加载一个JS文件，我会在下一篇文章详细说明的，请多多关注wp自学笔记！

扫码关注wpwp自学笔记

精选优质免费WordPress主题模板，分享最新WordPress实用建站教程！

记住我们的网址：ztJun.com