Using Github to Host Personal Blog

Table of Contents

• 1. 背景
  • 1.1. Github page
• 2. 设计
• 3. 实现
  • 3.1. 设置本地环境
  • 3.2. 设置项目
  • 3.3. 部署Travis
• 4. 参考

1. 背景

• Jekyll(后面两个小写的L)，用来将plain text的文档转换成静态的HTML的websites和blog
• Jekyll目前支持的Mark语言有Makrdown和Textile，不支持Asciidoc，但是可以通过插件的方式增加
• jekyll-asciidoc插件能让Jekyll支持Asciidoc
• Github支持展示静态html页面，但是不支持直接执行Jekyll进行转换
• Travis能监控Github提交，执行CI

1.1. Github page

• repo名字为username.github.io的proj将作为默认的主页
  
  • 地址为http://username.github.io
  • Github读取其master分支
• 其他repo也有项目页面
  
  • 地址为http://username.github.io/projname
  • Github读取其gh-pages分支

2. 设计

• 增加一个blog-src工程，存放源代码
• 增加一个shawn11zx.github.io工程，存放生成的HTML
• 增加一个travis项目，自动编译blog-src，并push到shawn11zx.github.io

3. 实现

3.1. 设置本地环境

• 安装ruby 2.x
• 设置ruby镜像

gem sources --add http://gems.ruby-china.org/ --remove https://rubygems.org/

• 安装ruby bundler

gem install bundler
gem install travis

• 设置ruby bundler镜像

bundle config mirror.https://rubygems.org http://gems.ruby-china.org

3.2. 设置项目

• 生成Jekyll目录结构（或者从jekyllthemes.org下载一个，如 Steve’s NGVB Theme)

jekyll new blog-src

• 在blog-src目录创建并编辑Gemfile（用于本地和CI执行jekyll时下载依赖项目）

source 'https://rubygems.org'

gem 'jekyll', '~> 3.1.0'
gem 'asciidoctor', '~> 1.5.0'
gem 'coderay', '~> 1.1.0'
gem 'rake-jekyll', '~> 1.1.0'

group :jekyll_plugins do
  gem "jekyll-asciidoc", '~> 1.0.0'
end

• 执行jerky serve实现WYSIWYG

cd blog-src
jekyll serve

• 向_posts目录增加Asciidoc格式的blog

3.3. 部署Travis

• 创建Travis项目和生成加密的Token 参考
  
  • 到github生成key
  • 到github创建repo
  • clone repo到本地
  • 到repo目录执行

travis encrypt -r user/repo GITHUB_TOKEN=[the token here]

• 创建.travis.yml文件，告诉Travis这是个ruby项目

language: ruby
rvm:
- 2.2.0
sudo: false
script: bundle exec rake deploy
env:
  global:
    secure: ....

• 创建Rakefile（用于Travis执行编译步骤）

该Rakefile通过rake-jekyll编译src repo，并push到目标repo

require 'rake-jekyll'

# This task builds the Jekyll site and deploys it to a remote Git repository.
# It's preconfigured to be used with GitHub and Travis CI.
# See http://github.com/jirutka/rake-jekyll for more options.
Rake::Jekyll::GitDeployTask.new(:deploy) do |t|

  t.deploy_branch = -> {
    'master'
  }

  t.remote_url = -> {
    url = 'https://github.com/shawn11ZX/shawn11zx.github.io.git'
    next url.gsub(%r{^https://}, "https://#{ENV['GH_TOKEN']}@") if ENV.key? 'GH_TOKEN'
    next url
  }

  t.ssh_key_file = '.deploy_key'
end

4. 参考

• Jekyll-asciidoc
• Jekyll
• Github page
• rake jekyll
• jekyll-asccidoc-quickstart
• Steve’s NGVB Theme