GitHub上搭建个人网站

2014-05-02

0.背景

准备重新捡起博客，记录自己的生活，特别是技术生活（过于私密的东西，也不敢往博客上放不是）。个人博客有两个途径：a.使用已有的博客网站; b.搭建自己的私人网站。调研了一下国内博客网站，（CSDN、javaEye、OSCHINA等）普遍文字格式、代码编排样式不是很喜欢（太挑剔了？对，我就是一个挑剔的人），这让自己转向私人博客。可以预想到，自己搭建要稍微复杂一点，话又说回来了，作为software engineer折腾网站也算看家本领了（我会告诉你我的目标是scientist么）。

既然要搭自己的私人博客，那选定什么框架/方案呢？之前使用WordPress搭过，但需要购买域名和空间；现在流行在GitHub上搭，并且不需要考虑域名和空间的问题，那就他了，上GitHub，走起（其实，国内也有一个类似的地方GitCafe，不过，出于装B需要，最终选定了GitHub）。

1.做什么？

目标：私人博客、自己搭建。

方式：GitHub Pages

2.怎么做？

初步分析，在GitHub上搭建博客，实质是：将自己的博客内容上传到GitHub上（因为GitHub提供了空间）；如果需要修改博客内容，则需要从GitHub上将download/pull下来；接下来就是让外面可以访问GitHub上的博客。总结一下，对应3个必要步骤：

1. GitHub上创建工程、并且能够将GitHub上的文件/代码，下载到本地；
2. 将本地的文件/代码，上传到GitHub上；
3. 配置GitHub，使其对外提供私人博客的访问页面；

好了，上面是凭空想出来的（任何地方搭建博客，都是上面的逻辑步骤，而不仅限于GitHub）；那实际如何操作呢？具体分为4个阶段：

1. 熟悉GitHub的基本操作（创建工程、上传代码、下载代码）；
2. 利用GitHub Pages功能，搭建简易网站；
3. 利用jekyll，增强网站功能（除了jekyll，还有其他的方式）；
4. 在jekyll框架下，依照个人偏好，进行定制；

3.实际操作

3.1GitHub的基本操作

• 安装使用Git（GitHub上传、下载文件的工具）
• GitHub上创建项目（其中包含了，GitHub上传文件的Git命令）
• GitHub上Fork项目（其中包含了，GitHub下载文件的Git命令）

补充：上传文件至GitHub；另外，向GitHub提交代码时，按照上面的操作方式，需要每次都输入GitHub的用户名和密码，可以采用SSH Keys的方式来解决此问题。

3.2如何搭建博客？

GitHub上对于个人博客的支持，实质是利用GitHub Pages功能来实现的，具体操作：GitHub Pages,认真读一遍，5mins，一步一步操作下来，简易博客就搭建成功了（一个简单的欢迎页面index.html）。

补充：扩展阅读GitHub Pages FAQ.

3.3Jekyll增强博客网站功能

详细阅读”3.2如何搭建博客“中提到的GitHub Pages的童鞋，在GitHub Pages页面最下端一定注意到了Blogging with Jekyll，对，就是他，读一遍，操作一下，搞定。

补充：jekyll用起来倒是用起来了，怎么发表一遍博文呢？这个…额…等到学会 “3.4 基于jekyll框架，定制博客” 再去写博客吧，现在建议把上面的操作反复看两遍，捋一捋逻辑流程。

3.4基于jekyll框架，定制博客

先看一下两个使用jekyll框架的博客：BeiYuu & Havee，他们对应的模版在GitHub上都可以找到：BeiYuu.com Template of GitHub & Havee.me Template of GitHub。

先膜拜一下上面两个博客模板，光彩夺目，亮瞎一双狗眼，好了，我能不能也搭建一个类似的博客？途径有一个：深入学习一下Jekyll的官方文档，补充：中文版本。（基于jekyll，如何定制博客，我将写一篇详细的介绍，敬请期待）

3.5绑定域名

几点：

• 购买域名
• GitHub上绑定域名：
  • 创建CNAME
  • 从GitHub Help 上搜索 custom domain
  • 可以参考:
    • Setting up an apex domain
    • Troubleshooting custom domains

TODO：整理GitHub上域名配置的基本原理：

• 整理A、C域名的区别
• …

4.FAQ

4.1使用google analytics来统计网站访问情况

1. 注册Google Analytics账户；
2. 在账户下，添加要监控的网站信息，Google Analytics会生成跟踪信息的JS片段；
3. 将上述JS片段插入到自己想要统计的页面上；

具体设置细节：请查看官方文档。

TODO：使用百度统计，替代google analytics

TODO：单独写一篇文章，关注几点：如何配置、基本原理。

参考资料：

• http://www.williamlong.info/archives/2214.html
• http://lusongsong.com/reed/548.html

4.2如何DISCUS作为评论插件？

1. 注册DISQUS账户；
2. 登录后，点击Add Disqus to your site按钮，操作下去，最终将获得相应的JS片段；
3. 将上述JS片段插入到自己想要包含评论的页面即可；

Update：（time：20170224）因为中国大陆无法访问 Disqus ，跟读者之间互动渠道就断了，因此，将 Disqus 切换为 多说：

1. 注册 多说 账号
2. 获得评论框的 JS 代码

update：（time：20170326）多说网站将在 6月1日 关闭，因此，需要切换到其他评论了，这次，切换到网易云跟帖

update：（time：20180121）由于网易云跟帖服务也关闭了，因此，重新切换 Disqus，但是，在中国大陆，需要「accross the wall」后，才能访问.

4.3配置网站，支持LaTeX语法

配置博客，支持LaTeX公式，此次设置kramdown来解析Markdown文件。

/*
If you have sufficient control over the publishing process
(e.g. you are running Jekyll yourself), an easy solution is
to switch the markdown parser to one that supports TeX.
*/

//For example, using kramdown:
gem install kramdown

//Change the markdown line in _config.yml to
markdown: kramdown

//and add something like
<script type="text/javascript" 
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
//to _layouts/default.html. 

//Now you can simply mark any mathematics in your posts with $$

原文链接：Using MathJax with Jekyll

4.4遇到的问题&解决办法？

1. 执行Git命令时，出错提示：（fatal: remote origin already exists.）
2. GitHub上markdown的解析引擎不同，会造成最终页面效果的差异
3. jekyll serve启动出错提示：（Liquid Exception: invalid byte sequence in GBK）见下文

修改\Ruby200\lib\ruby\gems\2.0.0\gems\jekyll-1.0.3\lib\jekyll目录下的convertible.rb文件，将其中：

self.content = File.read(File.join(base, name))

修改为：

self.content = File.read(File.join(base, name),:encoding=>"utf-8")

如果上述修改之后，仍然提示出错，则：...\lib\jekyll\tags目录下include.rb文件，类似对于convertible.rb文件的操作；

4.5MacPro 上搭建开发环境

参考 Blogging with Jekyll, 详细细节:

# 1.安装最新版 ruby
$ brew install ruby

# 2.安装 bundle 和 jekyll
$ gem install --user-install bundler

$ gem install --user-install jekyll

# 3. 退出 iterm 终端, 重新打开, 并安装 bundle
$ bundle install

Could not locate Gemfile

$ vim Gemfile
source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins

$ bundle install


# 4. 前往 jekyll blog 的目录下
$ cd /Users/guoning/ningg/github/ningg.github.com

# 5. 启动 jekyll 服务
$ bundle exec jekyll serve

# 下述方式, 只处理增量变更
$ bundle exec jekyll serve --incremental

# 6. 浏览器访问效果
http://127.0.0.1:4000

4.6开启HTTPS

采用 CNAME 设置域名的别名后, 在 project 的 settings 下, 能够看到提示:

• Your site is published at http://ningg.top/

现在的焦点: 如何开启 HTTPS 呢?

• TODO: 服务端需要额外配置证书, 暂时未启用 https 接入方式.

更多细节, 参考:

• GitHub Pages 对自定义域名支持 HTTPS

原文地址：https://ningg.top/build-blog-with-github/