Mac上使用Hexo、Github搭建博客

概况

本文简单介绍下如何在Mac下使用Hexo、Github搭建博客开发环境，以及搭建过程中出现问题及解决方案

Hexo概述

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。详细介绍可参考Hexo官方文档

Hexo安装

安装Hexo之前需要检查Mac中是否安装Node.js和Git，若已安装，可直接开始安装Hexo

安装Git

直接去Git官网下载支持Mac OS的最新版本安装即可

安装Node

在使用Mac支持的brew命令（brew install node）下载Node时，会安装最新版本，或者通过Node官网获取的最新版本（V6.2.0）直接完成安装，然后执行Hexo安装时，总会出现如下错误提示

npm ERR! Darwin 15.4.0
npm ERR! argv "/usr/local/bin/node" "/usr/local/bin/npm" "install" "-g" "hexo-cli"
npm ERR! node v6.2.0
npm ERR! npm  v3.8.9
npm ERR! path /usr/local/bin/hexo
npm ERR! code EEXIST
npm ERR! Refusing to delete /usr/local/bin/hexo: ../lib/node_modules/hexo/bin/hexo symlink target is not controlled by npm /usr/local
npm ERR! File exists: /usr/local/bin/hexo
npm ERR! Move it away, and try again.

npm ERR! Please include the following file with any support request:
npm ERR!     /Users/***/***/myBlog/npm-debug.log

此时去Node官网下载稳定的版本（V4.4.5）安装即可

安装Hexo

在上面两部都成功执行之后，开始完成Hexo的安装操作了，这里使用npm命令来完成操作，使用npm install -g hexo-cli时会出现如下错误提示

npm ERR! tar.unpack untar error /Users/***/.npm/hexo-cli/1.0.1/package.tgz
npm ERR! Darwin 15.4.0
npm ERR! argv "/usr/local/bin/node" "/usr/local/bin/npm" "install" "-g" "hexo-cli"
npm ERR! node v4.4.5
npm ERR! npm  v2.15.5
npm ERR! path /usr/local/lib/node_modules/hexo-cli
npm ERR! code EACCES
npm ERR! errno -13
npm ERR! syscall mkdir

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/hexo-cli'
npm ERR!     at Error (native)
npm ERR!  { [Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/hexo-cli']
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'mkdir',
npm ERR!   path: '/usr/local/lib/node_modules/hexo-cli',
npm ERR!   fstream_type: 'Directory',
npm ERR!   fstream_path: '/usr/local/lib/node_modules/hexo-cli',
npm ERR!   fstream_class: 'DirWriter',
npm ERR!   fstream_stack: 
npm ERR!    [ '/usr/local/lib/node_modules/npm/node_modules/fstream/lib/dir-writer.js:35:25',
npm ERR!      '/usr/local/lib/node_modules/npm/node_modules/mkdirp/index.js:47:53',
npm ERR!      'FSReqWrap.oncomplete (fs.js:82:15)' ] }
npm ERR! 
npm ERR! Please try running this command again as root/Administrator.

npm ERR! Please include the following file with any support request:
npm ERR!     /Users/***/***/myBlog/npm-debug.log</code></pre>

这是需要获取root权限来完成Hexo安装操作，即命令sudo npm install -g hexo-cli

Hexo使用（建站）

初始化配置

在本地新建一个目录专门用于存放Hexo初始化配置的相关文件，然后进入到该目录内完成如下操作

$ mkdir <folder>
$ cd <folder>
$ hexo init
$ npm install

或者直接执行下列命令，Hexo将会在指定文件夹中新建所需要的文件

$ hexo init <folder>
$ cd <folder>
$ npm install

Note：关于此部分的详细情况可参考Hexo建站

安装Hexo插件（可选）

可以通过选择如下某个命令完成相应插件的下载

npm install hexo-generator-index --save
npm install hexo-generator-archive --save
npm install hexo-generator-category --save
npm install hexo-generator-tag --save
npm install hexo-server --save
npm install hexo-deployer-git --save
npm install hexo-deployer-heroku --save
npm install hexo-deployer-rsync --save
npm install hexo-deployer-openshift --save
npm install hexo-renderer-marked@0.2 --save
npm install hexo-renderer-stylus@0.2 --save
npm install hexo-generator-feed@1 --save
npm install hexo-generator-sitemap@1 --save

例如，你要使用Github方式发布博客内容到Github Pages上，需要在已经安装hexo-deployer-git的前提下，才可以成功上传部署的静态博客内容到Github Pages上，不然会提示如下错误（此种情况可以参考Hexo部署）

ERROR Deployer not found: git

Hexo主题及其配置

Hexo主题

这里推荐使用NexT主题，其有三种外观可供选择，现已支持9种语言，当然还可以定制。具体内容可查看NexT官网

NexT主题下载可以进入到指定的Hexo初始化配置文件夹中，执行如下命令

$ cd your-hexo-site
$ git clone https://github.com/iissnan/hexo-theme-next themes/next

NexT主题配置

配置站点主题

接下来完成Hexo主题的配置，在Hexo初始化配置文件夹中打开站点配置文件（_config.yml文件），修改theme字段的值为next

theme: next

选择scheme

将主题配置文件的scheme字段修改为Mist值，详细介绍可参考NexT主题配置

#scheme: Muse
scheme: Mist
#scheme: Pisces

选择语言

将站点配置文件里的language字段修改为zh-Hans，即支持简体中文

language: zh-Hans

其它

还有其它的配置信息，具体可以参考NexT主题配置

Hexo使用

主要是结合Hexo命令完成相应操作

new

新建一篇文章。如果没有设置layout的话，默认使用站点配置文件中的default_layout 参数代替。如果标题包含空格的话，请使用引号括起来

$ hexo new [layout] <title>

generate

生成静态文件，提供-d（--deploy，文件生成后立即部署网站）和-w（--watch，监视文件变动）两个选项

$ hexo generate

server

启动服务器。默认情况下，访问网址为： http://localhost:4000/

$ hexo server

deploy

部署网站。提供-g选项（--generate，部署之前预先生成静态文件）

$ hexo deploy

Note：更多命令可参考Hexo命令

部署静态博客内容到Github

注册设置Github

1. 登录GitHub，注册自定义用户名如duslee
2. 在主页右下角创建New repository，name必须和用户名一致如duslee.github.io
3. 首次创建耐心等待10分钟左右审核，之后即可访问静态主页如http://duslee.github.io

同步内容到Github

1. 使用hexo clean命令完成清除操作（即清除已有的public文件夹）
2. 使用hexo g命令，生成新的public文件夹
3. 执行hexo d命令，完成内容部署到Github上
4. 访问博客地址，查看网页效果

Note：这里的具体细节可参考Hexo-Guide

未处理/说明细节

搜索功能实现

1. 这里使用Swiftype实现站内搜索功能，即Swiftype搜索。
2. 使用 Swiftype 之前需要前往 Swiftype 配置一个搜索引擎。 而后编辑站点配置文件， 新增 swiftype_key 字段，值为你的 swiftype 搜索引擎的 key。 详细的配置请参考： 第三方服务 - Swiftype

分类/标签显示

在站内博客的某篇文章中点击分类或标签时，按理来说应该进入分类或标签页面，但是如果出现如下错误提示

Cannot GET /categories/

或

Cannot GET /tags/

这时不要着急，只需新建分类页面或新建标签页面即可

Hexo迁移

Hexo迁移的详细操作可参考Hexo迁移

设置“阅读全文”

这种操作是为了在首页显示一篇文章的部分内容，并提供一个链接跳转到全文页面。本人采用的是<!-- more -->来实现，这也是Hexo推荐的方式。具体方案可参考如何设置“阅读全文”

设置页面文章的篇数

在Hexo里可以为首页和归档页面设置不同的文章篇数，但可能需要安装Hexo插件。详细步骤如下

安装插件

使用npm install --save命令来安装需要的Hexo插件

npm install --save hexo-generator-index
npm install --save hexo-generator-archive
npm install --save hexo-generator-tag

设置文章数量的配置

等待扩展全部安装完成后，在站点配置文件中，设定如下选项：

index_generator:
	per_page: 5

archive_generator:
	per_page: 20
	yearly: true
	monthly: true

tag_generator:
	per_page: 10

Note：具体的介绍可参考如何设置页面文章的篇数

更改内容区域的宽度

NexT主题对于内容的宽度设定如下：

• 700px，当屏幕宽度 < 1600px
• 700px，当屏幕宽度 < 1600px
• 移动设备下，宽度自适应

如果需要修改内容的宽度，此时需要编辑样式文件。编辑主题的source/css/_variables/custom.styl文件，新增变量：

// 修改成你期望的宽度
$ content-desktop = 700px

// 当视窗超过 1600px 后的宽度
$ content-desktop-large = 900px

Note：具体的介绍可参考如何更改内容区域的宽度

设置字体

字体的具体设置操作可参考NexT设置字体

Hexo支持脚注

Hexo默认的markdown编译插件是hexo-renderer-marked，不支持脚注，为解决脚注问题，可以使用hexo-footnotes插件

$ npm install hexo-footnotes --save

Note：Hexo官网插件下载地址

Hexo支持流表

使用hexo-diagram插件，其既支持流程图，也支持UML中的顺序图（Sequence Diagram）以及鲁棒图（Robustness Diagram），并且能生成SVG图形

Note：安装hexo-diagram过程中会出现错误提示

phantomjs-node: You don't have 'phantomjs' installed

经过多次分析得出phantomjs需要安装较低版本（v1.9.2）¹，才可以避免如下错误提示

phantom stdout: NETWORK_ERR: XMLHttpRequest Exception 101: A network error occurred in synchronous requests.

Note：hexo-diagram的使用可以参考Jumly官网的文档

字体颜色设置

非代码字体颜色设置

进入主题目录下source/css/_variables/base.styl文件中，修改全局链接颜色

// Global link color.
//$link-color                   = $black-light
//$link-hover-color             = $black-deep
//$link-decoration-color        = $grey-light
//$link-decoration-hover-color  = $black-deep

$link-color                   = $blue
$link-hover-color             = $red
$link-decoration-color        = $blue-deep
$link-decoration-hover-color  = $blue-deep

也可修改选中字体颜色

// Selection
$selection-bg                 = $blue-deep
//$selection-color              = white
$selection-color              = $red

还可修改使用一个单引号选中的内容的颜色

// Code & Code Blocks
// --------------------------------------------------
$code-font-family               = $font-family-monospace
$code-font-size                 = 13px
//$code-background                = $gainsboro
//$code-foreground                = $black-light
$code-background                = $gainsboro
$code-foreground                = $orange
$code-border-radius             = 4px

代码高亮设置

注意Markdown中代码块的使用，即把代码块包裹在``` 之间，在围栏式代码块中，可以指定一个可选的语言标识符，然后可以为它启用语法着色了

Note：使用反引号添加阴影效果时，如果内容里含有反引号，这时需要使用两个反引号来包裹内容，同时还要注意包裹内容和两个反引号之间留有空格

---

1. 1.下载地址 ↩