title: Hexo + github 博客搭建指南
date: 2018-01-14 02:18:16
tags: [hexo]
categories: 工具

用hexo + github 搭建博客

早在几年以前用hexo 搭建过一个博客系统部署到github上，但是一直没有用起来，平时都是习惯用mac 的备忘录记录一些东西。现在离职状态中准备找下个东家了，发现没个博客还是有些不妥，所以开始重新又弄了弄hexo，顺便也记录一下过程。

新建github仓库

仓库命名要同github账户名关连，格式如下:
仓库名：qiansr.github.io
其中qiansr是我的github账户名，qiansr.github.io这个仓库名也将是你项目的访问域名。注意“.github.io” 不能省略。

ssh密钥创建

ls -al ~/.ssh                                  //检查是否存在.pub
ssh-keygen -t rss -C “youremail@email.com”    //创建钥匙对
3. pbcopy < id_rsa.pub                       //拷贝公钥到剪切板:
4. 添加到gitlab或github账户

添加密钥

进入仓库=>Settings=>Deploy keys
Title:blog
Key:粘贴密钥
=> add key

测试添加ssh是否成功：

ssh -T git@github.com

==> 如果看到下面这句：Hi后面是你的用户名，就说明成功了
Hi qiansr! You've successfully authenticated, but GitHub does not provide shell access.

安装hexo

cd ～
npm install hexo -g

创建项目：

cd ./blog

vim package.json
A

修改package.json

{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "hexo": {
    "version": "3.4.4"
  },
  "dependencies": {
    "hexo": "^3.2.0",
    "hexo-deployer-git": "^0.3.1",
    "hexo-generator-archive": "^0.1.4",
    "hexo-generator-category": "^0.1.3",
    "hexo-generator-feed": "^1.2.2",
    "hexo-generator-index": "^0.2.0",
    "hexo-generator-sitemap": "^1.2.0",
    "hexo-generator-tag": "^0.2.0",
    "hexo-renderer-ejs": "^0.3.0",
    "hexo-renderer-marked": "^0.3.0",
    "hexo-renderer-stylus": "^0.3.1",
    "hexo-server": "^0.2.0"
  }
}

ESC + :wq           //保存退出vim
npm install

本地运行

hexo server
==>
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

在游览器中输入 http://localhost:4000/就可以看到你的博客了。

配置hexo与github连接

打开_config.yml文件
修改deploy值，在最后一行

deploy:
  type: git
  repo: https://github.com/qiansr/qiansr.github.io.git
  branch: master

把qiansr替换成你的github用户名

部署

hexo d -g

hexo 常用命令

hexo new "postName"         #新建文章
hexo new page "pageName"    #新建页面
hexo generate               #生成静态页面至public目录
hexo server                 #开启预览访问端口（默认端口4000，'ctrl + c'关闭server）
hexo deploy                 #将.deploy目录部署到GitHub
hexo help                   #查看帮助
hexo version                #查看Hexo的版本

主题资源

https://www.zhihu.com/question/24422335

hexo 完善博客设置

Hexo博客绑定域名

参阅《hexo搭建的Github博客绑定域名》：http://www.jianshu.com/p/cea41e5c9b2a

更换主题

git clone https://github.com/iissnan/hexo-theme-next themes/next
cd 根目录
vim _config.yml
找到theme属性，将其由landscape（默认主题）改为next。

主题设置

这里我选用的是NexT主题
在NexT主题目录下同样有一个名为_config.yml文件，称为主题配置文件，在其中找到scheme属性，
NexT主题默认使用Muse模式，你可根据自己的喜好，选择其中一种模式。

预览摘要

主题配置文件 auto_excerpt 属性：
enable: true
length: 150 #想要预览到的字数

评论功能

目前多说以挂，所以我们这里添加的是友言的评论系统
注册友言账号，获取uid （后台管理 => 用户ID）
打开主题配置文件找到youyan_uid属性设置uid

打赏功能

微信收款二维码     教程: https://jingyan.baidu.com/article/b907e627b641b646e6891c6b.html  
支付宝收款二维码    教程: http://blog.csdn.net/china8848/article/details/53504223  

二维码图片放到NexT根目录`/source/images/`文件夹下  
开启打赏功能主题配置文件，在其最后添加打赏的配置信息:

reward_comment: 坚持原创技术分享，您的支持将鼓励我继续创作！  
wechatpay: 图片链接或图片相对路径  
alipay: 图片链接或图片相对路径

侧边栏

主题配置文件 sidebar的display属性，display属性有四种显示模式：
post // 默认显示方式
always // 一直显示
hide // 初始隐藏
remove // 移除侧边栏

添加菜单选项（菜单栏标签页）

默认菜单只有首页、归档、关于三个选项，主题配置文件找到menu属性，通过去掉categories、 tags、about的的注释新增标签页：

// 命令行执行下列命令来添加分类页面
hexo new page "categories"
hexo new page “tags”
hexo new page "about"

会在source 目录下创建的三个目录和各自的index.md文件
打开index.md中在头部分别添加

type: “categories”
type: "tags"

当要为某一篇文章添加标签，在tags中添加，添加分类在categories中添加。

搜索功能

搜索的功能源于第三方服务——Algolia，接下来看看配置的步骤：注册Algolia官网，创建一个Index。
安装Hexo Algolia

npm install --save hexo-algolia

如果安装失败，找到package.json文件，修改其中的hexo-algolia属性值为^0.2.0，然后再重新安装
获取Key，修改站点配置Algolia官网的Dashboard => API Keys
编辑站点配置文件，在文件内容最后添加如下信息，

ApplicationID: ‘’
Search-Only API Key: 
Admin API Key: 
indexName: 
#其中apiKey就是Search-Only API Key：

更新Index配置好Key后，在Hexo根目录执行hexo algolia来更新Index
启用配置搜索功能修改主题配置文件，在其中找到algolia_search属性，将其enable子属性改为true，然后再看其labels子属性，修改相应的提示文本，使之更加适合自己的风格

<div color:red>（本人博客配置完了，发现搜索不到任何内容，目前不想再捣鼓了，有人遇到类似问题如果解决了麻烦贴一下解决办法）</div>

阅读次数

阅读次数统计是基于第三方服务——LeanCloud实现的，其配置详情如下：
创建LeanCloud账号进入LeanCloud官网完成注册:创建应用选择开发版 => 存储 =>
创建Class名称为Counter => 选择无限制选项
配置Key:单击应用Key，可以看到应用的App ID和App Key。主题配置文件中，在文件中找到leancloud_visitors属性，将enable设置为true，然后将之前复制的ID和Key粘贴到相应的属性中。

社交链接

在主题配置文件中找到social属性，在其下方添加社交链接，其格式为：

github：链接

添加链接图标
主题配置文件中找到social_icons，修改其状态值为true，然后配置对应链接的图标，其格式为：

github: Font Awesome中的图标的名字（区分大小写）
Font Awesome平台没有的图标，会显示默认。

友情链接
主题配置文件中找到links属性，修改links_title属性的值为“友情链接”，然后添加上好友的友链名称和地址，其格式如下：

名称: 链接

语言设定

在站点根目录下修改配置文件_cofig.yml中的language为zh-Hans（简体中文）

增改菜选项

修改在主题目录下配置文件_cofig.yml中的menu，增添一个something
修改主题目录下的languages文件中对应的zh-hans.yml文档
设置菜单项图标，对应的字段是menu_icons。格式为item name：icon name，其中item name与所配置的菜单名字对应，icon name是Font Awesome图标的名字。

设置侧栏位置

修改主题目录下sidebar的position值

设置头像

在站点根目录下载配置文件中新增avatar，值设置为头像的链接地址。地址可以是网络地址，也可以是本地地址（放置在source/images/ 目录下）

设置文章代码主题

在主题目录下修改配置文件highlight_theme，默认值为nomal。可以设置为night

NexT主题官方文档的链接

使用 GitHub Issues 搭建评论系统

基础使用

注册 OAuth Application
点击此处来注册一个新的 OAuth Application。其他内容可以随意填写，但要确保填入正确的 callback URL（一般是评论页面对应的域名）。
你会得到一个 client ID 和一个 client secret，这个将被用于之后的用户登录。
引入 Gitment
将下面的代码添加到你的页面：

<div id="container"></div>
<link rel="stylesheet" href="https://imsun.github.io/gitment/style/default.css">
<script src="https://imsun.github.io/gitment/dist/gitment.browser.js"></script>
<script>
var gitment = new Gitment({
  id: '页面 ID', // 可选。默认为 location.href
  owner: '你的 GitHub ID',
  repo: '存储评论的 repo',
  oauth: {
    client_id: '你的 client ID',
    client_secret: '你的 client secret',
  },
})
gitment.render('container')
</script>

注意，上述代码引用的 Gitment
将会随着开发变动。如果你希望始终使用最新的界面与特性即可引入上述代码。
如果你希望引用确定版本的 Gitment，则应该使用 npm 进行安装。

npm install --save gitment

关于构造函数中的更多可用参数请查看 Gitment Options

初始化评论
页面发布后，你需要访问页面并使用你的 GitHub 账号登录（请确保你的账号是第二步所填 repo 的 owner），点击初始化按钮。之后其他用户即可在该页面发表评论。

自定义
Gitment 很容易进行自定义，你可以写一份自定义的 CSS 或者使用一个新的主题。（主题可以改变 DOM 结构而自定义 CSS 不能）
比如你可以通过自定义主题将评论框放在评论列表前面：

const myTheme = {
  render(state, instance) {
    const container = document.createElement('div')
    container.lang = "en-US"
    container.className = 'gitment-container gitment-root-container'
    container.appendChild(instance.renderHeader(state, instance))
    container.appendChild(instance.renderEditor(state, instance))
    container.appendChild(instance.renderComments(state, instance))
    container.appendChild(instance.renderFooter(state, instance))
    return container
  },
}

const gitment = new Gitment({
  // ...
  theme: myTheme,
})

gitment.render('container')

更多自定义内容请查看文档。

其他问题

语言问题
考虑到 GitHub 本身使用英文，而本项目面向用户均为 GitHub 用户，所以作者没有提供中文支持的打算。实在有需求的可以通过自定义主题支持中文。

Q&A

问：本地部署成功了，也能预览效果，但执行hexo d -g后，使用 username.github.io 访问，无效果
答：首先确认 hexo d 命令执行是否报错，如果没有报错，再查看一下你的 github 的 username.github.io 仓库，你的博客是否已经成功提交了。如果没有成功，则查看你的本地git仓库的用户名和邮箱l设置是否和github账号邮箱一致。

git config user.emial
git config user.name

如果不一致要改为一致才行

git config user.emial github邮箱
git config user.name github账户名

重新执行：

hexo d -g

再检查是否成功。

问：多设备维护？

新建hexo分支  
git remote add origin https://github.com/用户名/仓库名.git
git checkout -b 分支名
git add .
git commit -m ""
git push origin hexo

#其他设备上clone下Github上新建的分支的文件到本地  
#在另一台设备上使用git指令下载Github新建分支上的文件:  

git clone -b 分支名 https://github.com/用户名/仓库名.git
npm install  
同步项目源文件到Github
git add .
git commit -m ""
// 先拉原来Github分支上的源文件到本地，进行合并
git pull origin 分支名
// 比较解决前后版本冲突后，push源文件到Github的分支
git push origin 分支名

运行hexo g报错?

FATAL Something's wrong...

这个问题我出现多次，是由于你写的markdowan语法有问题。检查对比语法看看是否正确，例如使用了代码中的符合
https://segmentfault.com/q/1010000003987383

替换markdown 默认渲染引擎
npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it --save