使用 Jekyll 搭建自己的 Github Pages

 
本文最后更新于

记录一下本人第一次搭建git pages的过程。谨以此文记录自己的操作过程。

想要操作高级玩法,一定要仔细阅读官方文档。了解liquid语法,yaml语法,jekyll架构。以及相关的HTML,css,javascript基础。

因为需要使用ruby语言,本人之前从未接触过它,对此有很大的抵触。网上找了很多教程都是基于MAC或者Linux系统的,本人使用win10,很怕弄不会又没有相关资料,于是还特意折腾了虚拟机安装了centos。按照教程一步步来,结果实际情况还是和各种教程的描述不一致。搞得本人头很大。后来耐心的查阅了很多资料,对github pages、jekyll及其相关工具有了更深的认识,于是照猫画虎的搭建成功了。接下来打算慢慢的修改成自己想要的样子。

jekyll 相关链接

Jekyll/Liquid API 语法文档

Liquid 模板语言 wiki

Xianda选的模板

使用Jekyll搭建自己的博客-全教程-简书

搭建一个免费的,无限流量的Blog—-github Pages和Jekyll入门

jekyll-now

使用 GitHub, Jekyll 打造自己的免费独立博客

Jekyll搭建写作环境问题集锦

Windows安装Jekll

windows上使用jekyll

windows 使用 ruby、jekyll 搭建 github pages

推荐几个老外写的教程:

http://jekyll-windows.juthilo.com(本人遇坑时参考了这篇)

http://yizeng.me/2013/05/10/install-jekyll-3-on-windows/

安装Ruby

官网下载ruby,windows系统推荐使用RubyInstaller。本人下载了.exe安装,会自动添加路径到path变量中。

安装完毕可以输入ruby -v验证。

安装RubyGems、Bundler

其实使用RubyInstaller会自动安装了gem。可直接输入gem -v验证。

  1. 官网下载RubyGems的zip包
  2. 解压zip文件并在命令行(cmd/git bash均可)cd到该目录
  3. 输入ruby setup.rb(管理员权限)

gem命令会把包安装在 类似D:\Ruby24-x64\lib\ruby\gems\2.4.0\gems的目录中,安装了jekyll会自动安装很多它的依赖包。都在这个目录里。

使用gem会自动安装帮助文档(rirdoc格式),因为我们可以在线查看,不需要下载,因此可以在~\.gemrc文件中添加两行:

install: "--no-ri --no-rdoc"
update: "--no-ri --no-rdoc"

可以执行touch ~/.genrc来创建文件名以.开头的文件。

这样使用gem命令时不安装帮助文档(否则它通常安装在D:\Ruby24-x64\lib\ruby\gems\2.4.0\doc目录)。

GEM 命令的其他操作:

#查看通过gem已安装插件:
$ gem list
#查看gem的源:
$ gem sources list
#可以添加/删除源:
$ gem sources --add https://gems.ruby-china.org/ --remove https://rubygems.org/
#清理旧的包:
$ gem cleanup
#基于`Gemfile`指定的依赖包执行命令:
$ bundle exec <command>
如果你使用 Gemfile 和 Bundler (例如:Rails 项目)

你可以用 Bundler 的 Gem 源代码镜像命令

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

接下来继续安装Bundler

gem install bundler # 安装bundler

安装完毕可以输入bundle -v验证。

现在我们可以根据项目根目录下Gemfile来使用bundle install或者bundle update命令进行安装/更新依赖了。

安装Jekyll

执行gem install jekyll即可自动安装jekyll的所以依赖包。也许或弹出防火墙提示,允许即可。依赖包数量比较多安装过程会慢,耐心等待安装完毕即可。

安装完毕输入jekyll -v验证。

如果安装jekyll出错

提示执行ridk install,则说明当前安装的是Ruby 2.4.x。需要在cmd运行ridk install安装 MSYS2 toolkit ,执行后输入1即可。如果下载过慢,可手动复制下载链接进行下载安装。

提示make不是内部或外部命令,则说明当前安装的是Ruby2.0-2.3。需要安装DEVELOPMENT KIT。按照下面方式操作:

官网下载DEVELOPMENT KIT,它是个自解压文件,运行后推荐解压到C:\RubyDevKit\。然后用git for windows的MingW64执行

# 切换到 解压文件夹
$ cd /C/RubyDevKit
# 初始化安装,会自动检查Ruby的安装路径
$ ruby dk.rb init

不过上一步可能会检查不出来,提示如下:

Initialization complete! Please review and modify the auto-generated
'config.yml' file to ensure it contains the root directories to all
of the installed Rubies you want enhanced by the DevKit.

需要手动修改 config.yml文件,确保config.yml中包含

- C:/Ruby23-x64

安装DevKit到ruby

$ ruby dk.rb install

不出意外会提示:

[INFO] Updating existing gem override for 'C:/Ruby23-x64'
[INFO] Installing 'C:/Ruby23-x64/lib/ruby/site_ruby/devkit.rb'

然后再尝试安装jekyll

$ gem install jekyll

笔者使用Ruby2.4,Ruby2.3均运行成功。

Jekyll 操作教程

想要读懂或编辑jekyll模板看这里:Jekyll/Liquid API 语法文档

$ jekyll build
# => 当前文件夹中的内容将会生成到 ./_site 文件夹中。

$ jekyll build --destination <destination>
# => 当前文件夹中的内容将会生成到目标文件夹<destination>中。

$ jekyll build --source <source> --destination <destination>
# => 指定源文件夹<source>中的内容将会生成到目标文件夹<destination>中。

$ jekyll build --watch

# => 当前文件夹中的内容将会生成到 ./_site 文件夹中,
# 查看改变,并且自动再生成。

$ jekyll serve

# => 当前文件夹中的内容将会生成到 ./_site 文件夹中。并搭建web服务。
# 可访问 http://localhost:4000 查看,方便本地调试。

搭建环境问题处理

搭建后执行jekyll命令如果出现报错,多为配置环境的问题。第一种方法通常是根据报错信息安装对应的依赖包即可,如:

gem install tzinfo-data

或者第二种方法,在根目录下的Gemfile文件里输入:

gem 'tzinfo-data'

本人使用gem install xxx会出错,采用的第二种方法。

### .svg 文件转 .png 和 .ico 文件工具

首先需要nodejs环境,官网下载即可。然后需要使用npm下载,npm服务器下载比较慢,可以选择淘宝镜像,具体操作见:https://npm.taobao.org/

npm install -g cnpm --registry=https://registry.npm.taobao.org

可参考:网站图标生成

拓展阅读

基于php的markdown博客搭建工具-gitblog

gitblog官网github地址

基于NodeJs的markdown博客搭建工具-hexo

hexo官网github地址

基于NodeJs的jekyll翻版工具-darko

github地址

https://github.com/thx/thx.github.io/blob/master/README.md

CentOS上使用jekyll(未完停更)

本人安装的是CentOS-7-x86_64-DVD-1708.iso镜像,提前安装好 VMWare Workstation。安装时软件选择->基本环境选的GNOME桌面,语言中文简体。然后点击开始安装,安装时设置好root账户密码。等待安装时过程中可以设置一个非root账户,结束后需要重启。然后进入 centos,右键打开终端,开始安装 jekyll 。

如果不是root账户,安装过程中也许会提示权限不足,请在执行的命令前加上sudo ,本人以下操作均是在root账户下操作。

参考:

Ruby on Rails 入门之:(1) Ruby, Rails, gem, bundler相关软件的安装

安装 rvm

curl -sSL https://get.rvm.io | bash -s stable

等待安装完毕,载入RVM环境(或者重新打开终端会自动载入):

source ~/.rvm/scripts/rvm

修改 RVM 下载 Ruby 的源,到 Ruby China 的镜像:

echo "ruby_url=https://cache.ruby-china.org/pub/ruby" > ~/.rvm/user/db

用 RVM 安装 Ruby 环境

检查一下rvm是否安装正确

rvm -v
rvm 1.29.3 (latest) by Michal Papis, Piotr Kuczynski, Wayne E. Seguin [https://rvm.io]
rvm requirements	//检查先决条件并安装
rvm list known		//写出已知的ruby版本

根据显示的版本信息,我选择了个当前最新版本:(ruby-head为dev版本)

rvm install ruby-2.4.1

等待安装结束,

vim Gemfile

I键,进入编辑模式,输入:

gem 'execjs'
gem 'therubyracer'

然后按ESC,输入:wq保存退出,然后

bundle install

……

折腾了好久,越弄入的坑越多。。。决定放弃。。。

教程未完,本人放弃了centos,回归熟悉的windows