# Vuepress博客教程

讲解如何使用Vuepress (opens new window) + Vssue (opens new window)(评论插件)搭建静态博客，然后部署到GitHub Pages上，并绑定到自定义域名（本博客是部署在阿里云上的，具体方法待日后有时间再分享）。

虽然Vuepress和Vssue的文档很详细，但是相信很多人是没有时间去完整阅读完它们的文档的或者说就算都看完了，可如何将它们各自多样的配置项结合在一起打造出一个满意的博客，还是会感觉一头雾水，这也是我刚接触时的感觉，所以写下来供大家参考。

该博客拥有以下特性：

对SEO友好
内置 Markdown 拓展
可在 Markdown 中使用 Vue
包含默认主题（响应式布局、自定义首页、内置搜索、可使用Algolia 搜索、可定制 navbar and sidebar、多语言支持等等）
可以自己用vue自定义主题
众多的插件
...

# 为什么选择这个方案

省事：
想起自己在校时，小小的尝试了一下Python，但掌握基本语法后却苦于无项目实践，便野心勃勃的说自己要用Python做一个博客。当时选择了Django（Python的Web框架） + Bootstrap（当时最火的前端响应式框架） + PostgreSQL（世界上最先进的开源数据库） + Linux（程序猿必会的操作系统）服务器，看上去这个技术方案是不是很牛逼！磕磕碰碰，恍恍惚惚的倒腾了两个月，也算搞出来点样子，去搜索引擎搜自己的博客，石沉大海一样，才知道还有个东东叫SEO！又是一顿学习，结果毕业后做了前端！沉寂一段时间后，终于认识到自己做博客本质是想通过写博客总结学习到的知识，写博客才是重点！生命有限，先不折腾。。。。。。
技术栈与前端友好：
vuepress和vssue都是js写的，vuepress是前端框架vue.js生态圈的一员。这样，在完成博客的核心要点——写博客之后，想对网站进行个性化设置、优化的时候也不需要花太多时间去点亮其他平时用的不多的技能球，还可以顺带提升自己对vue全家桶的认知，何乐而不为？此时，便是生命不息，折腾不止了！

# GitHub 准备

在GitHub上新建一个仓库，Repository name(仓库名字)格式必须为你的用户名.github.io，例如我的用户名为honkerzhou，所以我的GitHub Page的仓库名字就是honkerzhou.github.io。
注意：此仓库只能设为Public(公开的)，不能设为Private(私有的)。
其他的内容可以留待以后依据个人情况完善。

# 代码运行环境准备

TIP

由于每个人的实际情况不一样，故在这里不详细讲解安装过程，只附上各自的官网安装步骤方便大家正确安装与学习，如在实际操作过程中遇到问题，欢迎大家留言互动！

Node.js(版本 >= 8) (opens new window)
Yarn (opens new window) 或者 npm(安装Node.js的时候会一并安装)(两者都是包管理工具，由于VuePress官网更推荐用Yarn，故本教程后续主要用Yarn)
Git (opens new window)

# 开始项目

在自己想要存放代码的文件夹下打开终端(win下为命令行)

# 初始化项目，请根据实际情况自行填写相应提示内容，或者简单的一路回车就行，以后也是可以修改的
yarn init

# 将 VuePress 作为一个本地依赖安装
yarn add -D vuepress

# 新建一个 docs 文件夹
mkdir docs

# 新建一个 markdown 文件
echo '# Hello VuePress!' > docs/README.md

1
2
3
4
5
6
7
8
9
10
11

此时项目的目录结构如下：

.
├─ docs
│  └─ README.md
├─ node_modules
├─ package.json
├─ README.md
└─ yarn.lock

1
2
3
4
5
6
7

接着，在 package.json 里加一些脚本:

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
}

1
2
3
4

然后我们运行一下项目：

yarn docs:dev

终端输出：> VuePress dev server listening at http://localhost:8080/就说明运行成功了，这时在浏览里访问终端输出的地址http://localhost:8080/就可以看到“Hello VuePress!”了。

# 评论功能

首先，安装 vssue提供的vuepress插件及vssue提供的对应GitHub的API包：

yarn add -D @vssue/vuepress-plugin-vssue
yarn add -D @vssue/api-github-v3

1
2

然后，在docs/.vuepress/下新建一个config.js文件，输入以下代码：其中clientId和clientSecret的值的获取，请参照在如何在GitHub上创建一个新的 OAuth App (opens new window)，里面介绍的很详细。

module.exports = {
  plugins: {
    '@vssue/vuepress-plugin-vssue': {
      // 设置 `platform` 而不是 `api`
      platform: 'github',

      // 其他的 Vssue 配置，里面的值
      owner: '你的用户名',
      repo: '你的用户名.github.io',
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
    },
  },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

此时Vssue已经注册为 Vue 组件了，此时我们可以在 Markdown 文件中直接使用它。所以接下来，在本项目根目录下的README.md文件中输入以下代码：

<Vssue title="我是一个Issue" />

最后保存代码，浏览器页面自动刷新后便可看到评论系统了，此时只需要用页面上显示的管理员账号(GitHub账号)登录，便会自动初始化创建相关的Issues，从而进行评论。

TIP

一般修改了config.js,都需要重启服务后才能看到改动的效果。
先在终端按Ctrl+C停止服务，再输入yarn docs:dev启动服务。

# 部署到 GitHub Pages

首先，在你的项目根目录下，创建一个如下的 deploy.sh 文件:

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 绑定自定义域名，根据个人实际域名修改。
# 如果不需要绑定自定义域名，可将下面这行代码注释掉，例如博主的是www.honkerzhou.com
echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 发布到 https://<USERNAME>.github.io
git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

cd -

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

接着，在 package.json 里加一句脚本:

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs",
  "deploy": "bash deploy.sh"
}

1
2
3
4
5

保存后我们新建一个终端或者终止当前终端（Ctrl + C），输入：

yarn run deploy

成功之后，访问https://<USERNAME>.github.io，例如博主的https://honkerhzhou.github.io，便可看到“Hello VuePress!”和评论模块。
到了这里，其实博客就已经初步可以使用了。

# 绑定自定义域名

WARNING

本节内容假定你在deploy.sh里没有注释掉echo 'www.example.com' > CNAME，如果注释了的话，最好删除注释再重新部署一遍，可以省去其他操作。

在你的域名的购买商处添加两条CNAME的域名解析记录即可，以阿里云为例：

记录类型	主机记录	解析线路(isp)	记录值	TTL
`CNAME`	`www`	默认	`<USERNAME>.github.io`	10 分钟
`CNAME`	`@`	默认	`<USERNAME>.github.io`	10 分钟

静候10分钟（具体时间，依各域名服务商而异），访问www.example.com和之前访问https://<USERNAME>.github.io所见一样，便代表此步成功啦。

至此，本博客教程就结束了，如果对于后续个性化设置博客内容有疑问或者感兴趣的，欢迎在下方留言，共同学习，谢谢~

← 第一个路由 django-allauth入门学习和使用 →