【種樹】使用 Jekyll 和搭建 Github Pages

| | |

之前有一陣子在找合適的 blog 想用來存放文章，最好能支援數學公式、程式碼，若能使用 Markdown 來撰寫文章就更好了，另外版面最好整潔些不要像傳統 blog 有側欄的干擾（要求真多 XD

前後試過痞客邦、Blogger、Medium、Github Pages…，各有各的優缺點，但其實都不怎麼滿意，最後挑了Github Pages 主要是想玩玩 Jekyll 順便練習一下前端 XD

背景知識

Jekyll

雖然說是『想玩玩 Jekyll 』而選了 Github Pages，不過其實不懂 Jekyll 也沒差，知道它是一個 Ruby 編寫出來的 framework，讓使用者可以快速的建構出靜態頁面的 blog，並讓使用者可以用 Markdown 來編寫 HTML。有這些知識即可。

Git / Github

要建 Github Pages ，首先當必須有個 Github 帳號，如果不喜歡 Github 也可以考慮用 GitLab pages，兩個的步驟其實是一樣的，就看你喜歡章魚貓還是狐狸了。至於 git 的部分，只要會 commit 跟 push 就夠了（應該?），不會的話可以找猴子老師學學。對了，git 要記得安裝。

p.s. 是說我一直覺得『連猴子都能懂的Git入門指南』這個網站名稱有點嗆！？還是只有我這認為？不過它真的還滿淺顯易懂的，很適合 git 的入門。

建置步驟

1. 新增專案

新增名為「username.github.io」的專案，這個 username 指的是自己的 GitHub 帳號。這不僅是你的專案名稱，也是你的 blog 網址。


專案成立後，按照 Quick setup 的提示準備好專案的資料夾。

2. 安裝 Ruby

剛剛提過 Jekyll 是 Ruby 所編寫出來的 framework，因此在安裝 Jekyll 之前要先安裝，由於我家用的環境是 Windows （因為要打電動） ，所以以下的步驟是在 Windows 上進行的。在 Windows 平台上安裝 Ruby 可以使用 RubyInstaller，下載符合您自己系統的版本後，可以直接透過 UI 界面完成安裝步驟。

Note
使用 UI 界面安裝過程中，請記得勾選 Add Ruby executables to your PATH 這個選項，讓安裝程式會自動設定環境變數。
否則當你想使用 ruby 指令時，會出現不是內部或外部命令、可執行的程式或批次檔的錯訊息，如果出現該訊息就必須手動設定環境變數。


安裝完成後，接著開啟命令提示字元確認 Ruby 是否安裝成功，若成功應該可以看到目前的版號，請務必確認所安裝的 Ruby 是 Jekyll 所要求的 2.0 以上的版本 。

1
2
$ ruby -v
ruby 2.5.5p157 (2019-03-15 revision 67260) [x64-mingw32]

3. 安裝 Jekyll

Ruby 版本確認無誤後，就可以接著安裝 Jekyll 了

1
$ gem install jekyll

4. 建立 Jekyll 的網站

接下來將專案（e.g. myblog 資料夾）設為 Jekyll 的網站，由於我的專案中已經存在些檔案，所以我在指令的後面加上 force 避免覆蓋。網站設置完時，它會動配置一組預設主題 - minima。

1
$ jekyll new myblog  --force


到此網站就算建立完成了，若想在上線前預覽建置的結果，可先進入專案進行編譯。

1
2
$ cd myblog
$ jekyll serve

編譯結果可在瀏覽器輸入 http://localhost:4000 後查看。若可以順利執行，就將這次的 diff 進行 commit 後送上 github了。

5. debug啦

不過通常我做事都沒這順利…果不其然，當我執行 jekyll serve 時，結果出現下列錯誤訊息：

1
2
3
4
5
6
7
8
$ jekyll server
Traceback (most recent call last):
	5: from C:/Ruby25-x64/bin/jekyll:23:in `<main>'
	4: from C:/Ruby25-x64/bin/jekyll:23:in `load'
	3: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/jekyll-4.0.0/exe/jekyll:11:in `<top (required)>'
	2: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/jekyll-4.0.0/lib/jekyll/plugin_manager.rb:50:in `require_from_bundler'
	1: from C:/Ruby25-x64/lib/ruby/2.5.0/rubygems/core_ext/kernel_require.rb:59:in `require'
C:/Ruby25-x64/lib/ruby/2.5.0/rubygems/core_ext/kernel_require.rb:59:in `require': cannot load such file -- bundler (LoadError)


根據錯誤訊息 cannot load such file -- bundler 應該是我漏裝了bundler，因此用 gem 裝一下 bundler。

1
$ gem install bundler


不過裝完太心急，忘記 install 就直接執行 jekyll serve ，果不其然又收到錯誤 Bundler::GemNotFound 的錯誤。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$ jekyll server
Traceback (most recent call last):
	15: from C:/Ruby25-x64/bin/jekyll:23:in `<main>'
	14: from C:/Ruby25-x64/bin/jekyll:23:in `load'
	13: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/jekyll-4.0.0/exe/jekyll:11:in `<top (required)>'
	12: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/jekyll-4.0.0/lib/jekyll/plugin_manager.rb:52:in `require_from_bundler'
	11: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler.rb:107:in `setup'
	10: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/runtime.rb:20:in `setup'
	9: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/runtime.rb:108:in `block in definition_method'
	8: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/definition.rb:226:in `requested_specs'
	7: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/definition.rb:237:in `specs_for'
	6: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/definition.rb:170:in `specs'
	5: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/definition.rb:258:in `resolve'
	4: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/resolver.rb:22:in `resolve'
	3: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/resolver.rb:49:in `start'
	2: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/resolver.rb:255:in `verify_gemfile_dependencies_are_found!'
	1: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/resolver.rb:255:in `each'
C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-2.0.2/lib/bundler/resolver.rb:287:in `block in verify_gemfile_dependencies_are_found!': Could not find gem 'minima (~> 2.5) x64-mingw32' in any of the gem sources listed in your Gemfile. (Bundler::GemNotFound)


補一下，install 就 run 的起來了

1
$ bundle install

主題更換

如果不喜歡預設的 minima 的話，可以試著改寫 css 弄出自己獨一無二的 style。但如果你跟我一樣懶的話，那就考慮直接套用現成的主題來進行修改：

1. 挑選主題

網路上現成的主題還滿多的，可以直接在 google 上搜尋 jekyll theme 就會套出一堆網站了，像我是在 Jekyll Themes 上來進行挑選，挑了三個樣式較為簡潔的樣板，分別是：


其實有點大同小異啦，最後挑了第三個 jekyll-theme-next。運氣不錯，它還附有安裝教學，可以直接照著做就好，不過因為剛剛我已經把專案建好了我就不學它 git clone project 來執行 jekyll serve，而是直接複製貼上了 XD

2. 重新安裝相依性

主題套用完成後，因為各各主題所使用的套件不同，所以必需重新安裝相依性。

1
2
3
4
5
6
7
$ bundle install
Traceback (most recent call last):
	2: from C:/Ruby25-x64/bin/bundle:23:in `<main>'
	1: from C:/Ruby25-x64/lib/ruby/2.5.0/rubygems.rb:303:in `activate_bin_path'
C:/Ruby25-x64/lib/ruby/2.5.0/rubygems.rb:284:in `find_spec_for_exe': Could not find 'bundler' (1.17.1) required by your D:/CynthiaChuang.github.io/Gemfile.lock. (Gem::GemNotFoundException)
To update to the latest version installed on your system, run `bundle update --bundler`.
To install the missing version, run `gem install bundler:1.17.1`


又得到錯誤訊息了，按照它的提示先 update 後再重新安裝

1
2
$ bundle update --bundler
$ bundle install

3. 網站預覽

相依性檔案重新安裝完成後，就可以再次進行預覽，但我在這邊遇到點問題：

1
2
3
4
5
6
7
8
9
10
11
12
13
$ jekyll server
Traceback (most recent call last):
	10: from C:/Ruby25-x64/bin/jekyll:23:in `<main>'
	9: from C:/Ruby25-x64/bin/jekyll:23:in `load'
	8: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/jekyll-4.0.0/exe/jekyll:11:in `<top (required)>'
	7: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/jekyll-4.0.0/lib/jekyll/plugin_manager.rb:52:in `require_from_bundler'
	6: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-1.17.1/lib/bundler.rb:107:in `setup'
	5: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-1.17.1/lib/bundler/runtime.rb:26:in `setup'
	4: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-1.17.1/lib/bundler/runtime.rb:26:in `map'
	3: from C:/Ruby25-x64/lib/ruby/2.5.0/forwardable.rb:229:in `each'
	2: from C:/Ruby25-x64/lib/ruby/2.5.0/forwardable.rb:229:in `each'
	1: from C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-1.17.1/lib/bundler/runtime.rb:31:in `block in setup'
C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/bundler-1.17.1/lib/bundler/runtime.rb:319:in `check_for_activated_spec!': You have already activated concurrent-ruby 1.1.5, but your Gemfile requires concurrent-ruby 1.1.3. Prepending `bundle exec` to your command may solve this. (Gem::LoadError)


似乎是我所安裝的 concurrent-ruby 版本與主題中 Gemfile 所要求的版號不相符，不過這問題不大，在指令前加上 bundle exec 即可

1
$ bundle exec jekyll server

4. 繼續debug

反正，我每次安裝從來沒有一次照著說明書就可以安裝完成的（嘆

1
2
3
4
5
6
7
8
9
10
11
12
13
$ bundle exec jekyll server
Configuration file: D:/tmp/_config.yml
			Source: D:/tmp
	   Destination: D:/tmp/_site
Incremental build: disabled. Enable with --incremental
Generating...
Jekyll Feed: Generating feed for posts
GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
GitHub Metadata: Error processing value 'description':
Liquid Exception: No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository. in /_layouts/post.html
ERROR: YOUR SITE COULD NOT BE BUILT:
------------------------------------
No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository.


我拿到了一條 GitHub Metadata: No GitHub API authentication could be found 的錯誤訊息，google 了一下，網上很多方法 說是到 Github 申請一個 token，再配置一個環境變數。只是我覺得有點莫名其妙，為啥一定要跟 Github 綁定？ 最後在 jekyll-theme-next 的 issue 中，找到有人提出不用申請 token 的解法： 直接在 _config.yml 中，為空的 description 加上描述後就不會出現


在 description 加上描述後，錯誤訊息終於變了：

1
2
3
4
Rendering Markup: assets/css/style.scss
	Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
					Invalid CP950 character "\xE2" on line 5
jekyll 3.7.4 | Error:  Invalid CP950 character "\xE2" on line 5


照著說明，我在 assets/css 這個路徑下新增一個 style.scss 的檔案，檔案內容如下：

1
2
3
4
---
---

@charset "UTF-8";

撰寫文章

歷經千辛萬苦終於把網站弄起來了！之後只要將新寫好的 Markdown 文章，放在 _posts 資料夾下，文章就會顯示在網站上。不過要注意以下幾點：

  • Markdown 的檔案命名必須為 YYYY-MM-DD-{article_title}.md。

  • Markdown 內容的開頭應該類似下方，不過不同的主題可能會略有不同，請按照各自主題的定義來撰寫：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    ---
title: 文章標題
date: 2013-12-24 23:29:53
categories:
- Foo
tags:
- Foo
- Bar
- Baz
--- 

// 以下開始撰寫你的文章

    2019/12/13 紀錄
    目前我使用 jekyll-theme-next 測試 categories 無法接受中文，一旦使用中文，會導致找不到該頁面，而導向 404 Page (#63)

後記

不過雖然把 Github Pages 建起來了，不過都沒怎麼更新，主要是它的預覽實在有點麻煩，我不能在行動裝置或非本人的電腦進行，有點小苦惱，再加上後來有找到用 Markdown 寫 Blogger 的方法，所以還是以 Blogger 為主（雖然那邊也是在長草）。

參考資料

  1. Jekyll 介紹 ｜卡斯伯 Blog - 前端，沒有極限
  2. 在 Windows 安裝 Ruby on Rails ｜ShunNien’s Blog
  3. 使用 Jekyll + Github 來建立一個部落格 ｜MMiooiMM
  4. [Ting’s筆記Day2] 在Github用Jekyll創建自己的blog ｜iT 邦幫忙
  5. 如何在GitHub Pages使用Jekyll建置部落格 ｜Yung-An’s World!
  6. 使用 GitHub Pages 和 Jekyll 來建立 Blog ｜Xaree
  7. Jekyll使用教程笔记 一 ｜掘金
  8. rubygems - cannot load such file – bundler/setup (LoadError) ｜Stack Overflow
  9. jekyll s出现…(Bundler::GemNotFound)问题解决方法 ｜简书
  10. 【已解决】GitHub Metadata:No GitHub API authentication — 0xl2oot
  11. 本地运行报错 · Issue #19 · Simpleyyt/jekyll-theme-next ｜GitHub
  12. Scss encountered an error while converting ‘assets/css/style.scss’ · Issue #185 · mmistakes/jekyll-theme-hpstr ｜GitHub
  13. 撰写博客 ｜Jekyll • 简单静态博客网站生成器