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个必要步骤：
- GitHub上创建工程、并且能够将GitHub上的文件/代码，下载到本地；
- 将本地的文件/代码，上传到GitHub上；
- 配置GitHub，使其对外提供私人博客的访问页面；
好了，上面是凭空想出来的（任何地方搭建博客，都是上面的逻辑步骤，而不仅限于GitHub）；那实际如何操作呢？具体分为4个阶段：
- 熟悉GitHub的基本操作（创建工程、上传代码、下载代码）；
- 利用GitHub Pages功能，搭建简易网站；
- 利用jekyll，增强网站功能（除了jekyll，还有其他的方式）；
- 在jekyll框架下，依照个人偏好，进行定制；
3.实际操作
3.1GitHub的基本操作
补充：上传文件至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 - 可以参考:
TODO：整理GitHub上域名配置的基本原理：
- 整理A、C域名的区别
- …
4.FAQ
4.1使用google analytics来统计网站访问情况
- 注册Google Analytics账户；
- 在账户下，添加要监控的网站信息，Google Analytics会生成跟踪信息的JS片段；
- 将上述JS片段插入到自己想要统计的页面上；
具体设置细节：请查看官方文档。
TODO：使用百度统计，替代google analytics
TODO：单独写一篇文章，关注几点：如何配置、基本原理。
参考资料：
- http://www.williamlong.info/archives/2214.html
- http://lusongsong.com/reed/548.html
4.2如何DISCUS作为评论插件？
- 注册DISQUS账户；
- 登录后，点击
Add Disqus to your site按钮，操作下去，最终将获得相应的JS片段； - 将上述JS片段插入到自己想要包含评论的页面即可；
Update：（time：20170224）因为中国大陆无法访问 Disqus ，跟读者之间互动渠道就断了，因此，将 Disqus 切换为 多说：
- 注册 多说 账号
- 获得评论框的 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遇到的问题&解决办法？
- 执行Git命令时，出错提示：（fatal: remote origin already exists.）
- GitHub上markdown的解析引擎不同，会造成最终页面效果的差异
- 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接入方式.
更多细节, 参考:
原文地址：https://ningg.top/build-blog-with-github/