如何用github-hexo搭建一个静态博客

Hexo搭建Github静态博客

1. 环境环境

1.1 安装Git

请参考【1】

1.2 安装node.js

下载：http://nodejs.org/download/

可以下载 node-v0.10.33-x64.msi

安装时直接保持默认配置即可。

2. 配置Github

1.1 建立Repository

建立与你用户名对应的仓库，仓库名必须为【your_user_name.github.io】

1.2 配置SSH-Key

参考【1】

3. 安装Hexo

关于Hexo的安装配置过程，请以官方Hexo【2】给出的步骤为准。

3.1 Installation

打开Git命令行，执行如下命令

$ npm install -g hexo

3.2 Quick Start

1. Setup your blog

在电脑中建立一个名字叫「Hexo」的文件夹（比如我建在了D:\Hexo），然后在此文件夹中右键打开Git Bash。执行下面的命令

$ hexo init

[info] Copying data

[info] You are almost done! Don't forget to run `npm install` before you start b

logging with Hexo!

Hexo随后会自动在目标文件夹建立网站所需要的文件。然后按照提示，运行 npm install（在 /D/Hexo下）

npm install

会在D:\Hexo目录中安装 node_modules。

2. Start the server

运行下面的命令（在 /D/Hexo下）

$ hexo server

[info] Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

表明Hexo Server已经启动了，在浏览器中打开 http://localhost:4000/，这时可以看到Hexo已为你生成了一篇blog。

你可以按Ctrl+C 停止Server。

3. Create a new post

新打开一个git bash命令行窗口，cd到/D/Hexo下，执行下面的命令

$ hexo new "My New Post"

[info] File created at d:\Hexo\source\_posts\My-New-Post.md

刷新http://localhost:4000/，可以发现已生成了一篇新文章 "My New Post"。

NOTE：

　举老　有一个问题，发现 "My New Post" 被发了2遍，在Hexo server所在的git bash窗口也能看到create了2次。

$ hexo server

[info] Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

[create] d:\Hexo\source\_posts\My-New-Post.md

[create] d:\Hexo\source\_posts\My-New-Post.md

经验证，在hexo new "My New Post" 时，如果按Ctrl+C将hexo server停掉，就不会出现发2次的问题了。

所以，在hexo new文章时，需要stop server。

4. Generate static files

执行下面的命令，将markdown文件生成静态网页。

$ hexo generate

该命令执行完后，会正哗升在 D:\Hexo\public\ 目录下生成一系列html，css等文件。

5. 编辑文章

hexo new "My New Post"会在D:\Hexo\source\_posts目录下生成一个markdown文件：My-New-Post.md

可以使用一个支持markdown语法的编辑器（比如 Sublime Text 2）来编辑该文件。

6. 部芦罩署到Github

部署到Github前需要配置_config.yml文件，首先找到下面的内容

# Deployment

## Docs: http://hexo.io/docs/deployment.html

deploy:

type:

然后将它们修改为

# Deployment

## Docs: http://hexo.io/docs/deployment.html

deploy:

type: github

repository: git@github.com:zhchnchn/zhchnchn.github.io.git

branch: master

NOTE1:

Repository：必须是SSH形式的url（git@github.com:zhchnchn/zhchnchn.github.io.git），而不能是HTTPS形式的url（https://github.com/zhchnchn/zhchnchn.github.io.git），否则会出现错误：

$ hexo deploy

[info] Start deploying: github

[error] https://github.com/zhchnchn/zhchnchn.github.io is not a valid repositor URL!

使用SSH url，如果电脑没有开放SSH 端口，会致部署失败。

fatal: Could not read from remote repository.

Please make sure you have the correct access rights

and the repository exists.

NOTE2：

如果你是为一个项目制作网站，那么需要把branch设置为gh-pages。

7. 测试

当部署完成后，在浏览器中打开http://zhchnchn.github.io/（https://zhchnchn.github.io/） ，正常显示网页，表明部署成功。

8. 总结：部署步骤

每次部署的步骤，可按以下三步来进行。

hexo clean

hexo generate

hexo deploy

9. 总结：本地调试

1. 在执行下面的命令后，

$ hexo g #生成

$ hexo s #启动本地服务，进行文章预览调试

浏览器输入http://localhost:4000，查看搭建效果。此后的每次变更_config.yml 文件或者新建文件都可以先用此命令调试，尤其是当你想调试新添加的主题时。

2. 可以用简化的一条命令

hexo s -g

3.3 命令总结

3.3.1 常用命令

复制代码

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的版本

复制代码

3.3.2 复合命令

hexo deploy -g #生成加部署

hexo server -g #生成加预览

命令的简写为：

hexo n == hexo new

hexo g == hexo generate

hexo s == hexo server

hexo d == hexo deploy

4 配置Hexo

4.1 配置文件介绍

下面的各个部分的介绍，请直接参考【3】。

1. 默认目录结构介绍

2. _config.yml配置文件介绍

NOTE：在修改_config.yml配置文件时，按照【3】的介绍进行修改后，重新 hexo clean 或者hexo deploy时，可能会出现如下错误：

复制代码

$ hexo clean

[error] { name: 'HexoError',

reason: 'can not read a block mapping entrya multiline key may not be an imp

licit key',

mark:

{ name: null,

buffer: '# Hexo Configuration\n## Docs: http://hexo.io/docs/configuration.h

tml\n## Source: https://github.com/hexojs/hexo/\n\n# Site\ntitle: Zhchnchn\nsubt

itle: Coding on the way\ndescription: Zhchnchn\'s blog\nauthor: Zhchnchn\nemail:

115063497@qq.com\nlanguage:zh-CN\n\n# URL\n## If your site is put in a subdirect

......

,

position: 249,

line: 12,

column: 0 },

message: 'Config file load failed',

domain:

{ domain: null,

_events: { error: [Function] },

_maxListeners: 10,

members: [ [Object] ] },

domainThrown: true,

stack: undefined }

复制代码

我的_config.yml配置文件是一个空行，所以错误肯定在前面，经过对比发现，我前面修改了一下 # Site的各项设置，在冒号:后面没留空格导致了该问题，请对比一下下面的区别：

错误的设置：

author:Zhchnchn

email:XXX@qq.com

language:zh-CN

正确的设置：

author: Zhchnchn

email: XXX@qq.com

language: zh-CN

3. 各个主题下的目录介绍（hexo\themes\下的modernist主题为例）

4.2 安装主题

Hexo提供了很多主题，具体可参见Hexo Themes【4】。这里我选择使用Pacman主题。具体设置方法如下【5】

4.2.1 安装

1. 将Git Shell 切到/D/Hexo目录下，然后执行下面的命令，将pacman下载到 themes/pacman 目录下。

$ git clone https://github.com/A-limon/pacman.git themes/pacman

2. 修改你的博客根目录/D/Hexo下的config.yml配置文件中的theme属性，将其设置为pacman。

3. 更新pacman主题

cd themes/pacman

git pull

NOTE：先备份_config.yml 文件后再升级

4.2.2 配置

如果pacman的默认设置不能满足需要的话，你可以修改 /themes/pacman/下的配置文件_config.yml来定制。

各个config的含义，请参考【5】中的介绍。

4.2.3 评论框

静态博客要使用第三方评论系统，pacman配置了多说评论系统（/themes/pacman/_config.yml），默认关闭，只要将其打开即可:false->true。直接用你的微博/豆瓣/人人/百度/开心网帐号登录多说，即可发表平评论。

#### Comment

duoshuo:

enable: true ## duoshuo.com

short_name:## duoshuo short name.

4.2.3 统计

1. pacman配置了google analysis系统（/themes/pacman/_config.yml），默认关闭，将其打开。

2. 需要注册google analysis服务，以获得 跟踪 ID。

如果已有google账户的话，可以直接注册。注册时，需要正确填写 网站的URL。注册成功后，会得到一个跟踪ID，以及一段跟踪代码。

3. pacman配置了google analysis系统，将其打开

#### Analytics

google_analytics:

enable: true

id: UA-57032437-1 ## e.g. UA-1766729-8 your google analytics ID.

site: auto ## e.g. yangjian.me your google analytics site or set the value as auto.

4. 在themes\pacman\layout\_partial\google_analytics.ejs 中，已经将google的跟踪代码添加进来了【3】。

复制代码

<% if (theme.google_analytics.enable){ %>

<script type="text/javascript">

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=ri[r]=i[r]||function(){

(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date()a=s.createElement(o),

m=s.getElementsByTagName(o)[0]a.async=1a.src=gm.parentNode.insertBefore(a,m)

})(window,document,'script','//www.google-analytics.com/analytics.js','ga')

ga('create', '<%= theme.google_analytics.id %>', '<%= theme.google_analytics.site %>')

ga('send', 'pageview')

</script>

<% } %>

复制代码

而且会将/themes/pacman/_config.yml中的id和site值读取进来。

5. 如果设置不起作用，请试试在\themes\pacman\layout\_partial\head.ejs文件中最后，</head>之前，添加上下面的语句试试。

<%- partial('google_analytics') %>

4.3 Custom 404页面

1. 网上大多数教程都将其说的极其简单：“直接在根目录下创建自己的 404.html 就可以”。但我却在这儿废了不少时间，究其原因是大家觉得太简单而说的不够明白。“根目录下”指的不是Hexo目录下，而是Hexo/source目录下。

2. 404.html的内容可以设置为下面的内容【6】（NOTE： _config.yml中的permalink_defaults属性不需要修改）。

复制代码

---

layout: default

---

<html>

<head>

<meta charset="UTF-8" />

<title>404</title>

</head>

<body>

<script type="text/javascript" src="http://www.qq.com/404/search_children.js" charset="utf-8"></script>

</body>

</html>

复制代码

也可以简化为这一行：

<script type="text/javascript" src="http://www.qq.com/404/search_children.js" charset="utf-8"></script>

4.4 安装插件

4.4.1 sitemap插件

1. 可以将你站点地图提交给搜索引擎，文件路径\sitemap.xml。

2. 安装

$ npm install hexo-generator-sitemap

3. 启用，修改Hexo\_config.yml，增加以下内容

复制代码

# Extensions

Plugins:

- hexo-generator-sitemap

#sitemap

sitemap:

path: sitemap.xml

复制代码

4. 使用方法

（1）访问 http://localhost:4000/sitemap.xml，即可看到站点地图。

（2）那么怎么将它显示在页面中呢【7】？

可以修改themes/pacman（也就是你正在使用的那个theme）下的 _config.yml，在 menu 节点下添加下面的内容（下面要介绍的RSS插件也同样）

menu:

Home: /

Archives: /archives

Rss: /atom.xml

Sitemap: /sitemap.xml

修改后的效果如图所示：

5. 如何向google提交sitemap

Sitemap 可方便管理员通知搜索引擎他们网站上有哪些可供抓取的网页。向google提交自己hexo博客的sitemap，有助于让别人更好地通过google搜索到自己的博客。

如何向google提交sitemap，请参考【8】。

6. 升级插件

$ npm update

7. 卸载插件

$ npm uninstall hexo-generator-sitemap

4.4.2 feed插件

1. RSS的生成插件，你可以在配置显示你站点的RSS，文件路径\atom.xml。

2. 安装

$ npm install hexo-generator-feed

3. 启用，修改Hexo\_config.yml，增加以下内容

复制代码

# Extensions

Plugins:

- hexo-generator-feed

- hexo-generator-sitemap

#Feed Atom

feed:

type: atom

path: atom.xml

limit: 20

复制代码

4.使用方法

参见sitemap插件介绍

5. 优化Hexo

5.1 添加“Fork me on Github” ribbon

给blog主页添加一个“Fork me on Github”的绶带（ribbon）【9】，比如选择了红色的ribbon，将相应代码复制到Hexo正在使用的theme下layout.ejs中。比如我使用的pacman theme，那么将下面的代码（注意将you改为你自己的github上的注册名）

<a href="https://github.com/zhchnchn"><img style="position: absolutetop: 0left: 0border: 0" src="https://camo.githubusercontent.com/82b228a3648bf44fc1163ef44c62fcc60081495e/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f6c6566745f7265645f6161303030302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_left_red_aa0000.png"></a>

粘贴到 themes\pacman\layout\layout.ejs中，放置在 最后，标签</body>之前即可。

6 其他

6.1 中文乱码

在md 文件中写中文内容，发布出来后为乱码，原因是md的编码不对，将md文件另存为“UTF-8”编码的文件即可解决问题。

References

【1】Windows下Git安装指南（http://www.cnblogs.com/zhcncn/p/3787849.html）

【2】Hexo （https://github.com/hexojs/hexo）

【3】hexo你的博客（http://ibruce.info/2013/11/22/hexo-your-blog/）

【4】Hexo All Themes（https://github.com/hexojs/hexo/wiki/Themes）

【5】Pacman主题介绍（http://yangjian.me/pacman/hello/introducing-pacman-theme/）

【6】hexo添加404页面(http://ruocaiwu.github.io/2014/08/14/hexo%E6%B7%BB%E5%8A%A0404%E9%A1%B5%E9%9D%A2/)

【7】如何搭建一个独立博客——简明Github Pages与Hexo教程（http://cnfeat.com/2014/05/10/2014-05-11-how-to-build-a-blog/）

【8】如何向google提交sitemap（详细）(http://fionat.github.io/blog/2013/10/23/sitemap/)

【9】GitHub Ribbons(https://github.com/blog/273-github-ribbons)

Github在3月19号开放了新的项目展示页面（Showcase），Showcase根据项目属性来组织、定义一系列的开源项目列表，可以更清晰的发现你所需要的开源项目。在3月26日的Showcase中，Github放出了一个新的类目：支撑Github的开源技术，这里列举了Github所使用的一些主要的开源项目。

如下是这些开源项目的介绍：

linguist

语言识别库，能够自动根据项目的代码来识别你所使用的语言。 在你的项目源代码页面，可以看到一个彩条，点开以后会显示项目中的编程语言比例。linguist主要通过文件的后缀来识别，对于一些通用的扩展名，例如.m文件，linguist通过一些语言的特征片段来做判断。由于编程语言很多，linguist还不能覆盖所有语言的检测。

jquery-pjax

pjax是Github的联合创始人之一defunkt的作品，它使用html的pushState特性与ajax，可以实现页面内容动态局部刷新，当点击项目源代码页面中具体的一个文件或者文件夹时，你将会看到页面的其他部分是不变的，只有定义的页面DOM会刷新，这里使用的就是pjax。

elasticsearch

Eleasticsearch支撑了Github的搜索功能，2年之前Github使用Solor做搜索，随着用户和托管项目的增加，索引的大小超过了solor节点的最大存储空间，也出现了很多的问题，Github团队在思考解决方案时决定使用Elasticsearch做替换。Github最开始使用ES时，使用了44台亚马逊EC2实例，每台实例配备2T的存储，其中8台实例指负责查询请求。目前，Github已经将原有的EC搜索集群迁移到了东海岸的一个数据中心，使用8台物理主机替换了44台EC2。

Rails

Ruby实现派高的MVC Web框架。Github的用户界面和功能大部分基于Rails构建，不过需要注意的是现在虽然Rails的项目版本已经发展到了Rails 4，但是Github依旧使用的是自己维护的2.3分支，对于不保持和现有的Rails主版本号一致的原因，Github员工Kneath做了如下的解释：

. 花更过的时间来升级更新Rails，将会减少为用户构建新特性的时间，我们更关注用户；

. 性能问题是一个很重要的考虑。在过去的几年中，我们极大的减少了响应时间。而升级Rails不仅会谈喊带来一个更慢的框架，而且还会引入一个不同的架构——我们需要再根据新的框架特性来定位优化性能。我们对于现有的框架已经做了很多的优化以保持性能稳定，最主要的是：将时间花费在升级上不会让我们的架构更快。

. 过去的三年我们一直在升级这个堆栈，不升级Rails版本我们依然可以使用新的特性。

Redis

Redis是K/V存储系统，知名的NoSQL实现之一，在Github，主要使用Redis来进行队列中的异常处理。在Github早期，曾尝试过很多的基于Ruby的队列机制，也曾使用Amazon SQS，但是这些方案都不能在Github快速增长的同时满足稳定性要求，最终Github迁移到了使用Redis的技术方案resque。

sprocket

Sprocket是一个网站资源打包的Ruby库，它不仅能够管理含羡野JavaScript和CSS资源，还可以按照pipline的方式来流式预处理CoffeeScript、Sass、SCSS和LESS代码等；

libgit2

libgit2是一个可移植、纯C语言实现的Git核心方法类库，提供API重新链入Git方法。Github的背后使用的原生的git来实现commit、push等功能，但是使用libgit2来针对桌面应用调用、Ruby代码中调用等；

rugged

libgit2的Ruby类库；

bcrypt-ruby

OpenBSD bcypt()密码哈希算法的Ruby实现；

html-pipeline

html-pipline是一个gem包，可以将现有Github前端HTML中的一些特性进行流式处理，例如在Github的评论框中，你可以@某一个人、输入emoji的表情、使用markdown的语法来写内容等，但是这些都是由单独的插件来控制的，html-pipeline可以流式的使用相应的插件处理原始内容，例如先将markdown转义成html，继而自动添加emoji表情，然后进行代码的语法高亮等。

gemoji

在2013年的QCon北京前夜：Github Drink Up活动中，来自Github的工程师Tim在现场的活动中谈到了他们的一个文化：使用emoji。他解释道：“很多情感使用文字不能做出形象的表达，但是使用emoji表情却能够起到不一样的效果”。在Github现有评论框或其他内容中，都可以看到emoji的身影，所使用的就是gemoji这个gem包。

jekyll

Jekyll是一个静态博客生成的程序，Github中项目的Page页面，默认选型使用的就是jekyll。

gollum

Gollum是一套基于git的wiki系统，Github项目的wiki系统背后使用的就是这套开源框架；

octokit.rb

Github API的官方Ruby SDK；

Hubot

Hubot是Github自行开发的一个聊天机器人，当然它已经超过了聊天机器人的范畴，Github作为一个异步办公的团队，日常的协作、沟通很大部分依赖于聊天室，通过Hubot，Github的员工可以在聊天室中给机器人定制一些特定的回复、3D打印模型，甚至通过hubot来部署生成环境的代码、获取服务状态等，在2013年的QCon北京中，Giuthub的工程曾针对如何使用Hubot做运维进行过分享：《ChatOps at GitHub》。

d3

d3是使用JavaScript实现的数据可视化框架，使用HTML、SVG和CSS等，在d3的基础之上发展处诸如crossfilter、NVD3.js等一系列扩展或者简化框架，并且形成了一个良好的社区。作者mbostock目前供职于NYTimes，d3是他的博士论文项目，目前Github使用d3来展示托管项目提交历史、记录等的可视化效果图。

plax

plax是控制视差元素的JavaScript类库，你可以在404、505等页面看到它的实现效果。

ace

Ace是一个使用Javascript开发的代码编辑器，具备语法高亮、快捷键绑定等特性， Github使用Ace实现基于web的代码编辑功能。

zepto

Zepo是一个JavaScript框架，其特点是兼容现有jQuery API的同时，自身体积十分小；

zeroclipborad

Github的“点击复制到粘贴板”的功能就是使用的zeroclipboard，zeroclipboard使用一个不可见的Adobe Flash动画来实现复制粘贴，并提供Javascript的API接口以供调用。

charlock_holmes

charlock_holmes用来检测字符编码格式，并可以自动将字符编码转化成UTF-8。

puppet

服务器运维工具，可以进行自动化部署、集群管理等。

moment

moment是一个日期框架，用于解析、验证、格式化日期等，其中一个常用的功能是将原始的Javascript时间类型转化成方便阅读的时间说明格式，例如：”2小时之前“、”3天之前“这种形式。

bower

前端资源包管理工具，可以通过bower install <package>的形式将常用的前端资源下载到本地的项目目录中，例如：bower install bootstrap将会自动下载bootstrap的项目资源到本地的项目目录中，不需要自己手动来下载、移动资源文件，并且通过配置文件可以方便分享给同事、简化项目初始化等；

resque

Resque是Github Enterprise中使用的一个基于Redis的后台作业控制系统，提供可视化的界面，可以方便的监控后台作业的运行状态和监控情况。

另外，Github还发布了“支撑Github Windows客户端的开源项目”和“支撑Github Mac客户端的开源项目”两个Showcase。

---