在代碼倉庫 settings 中開通 Github Pages 後，該倉庫目標位置（gh-pages 分支、/ 或 /docs/）的 markdown 文件會在 Github 的服務器上被 Jekyll 渲染為同名的 html 文件，以提供網頁服務。

關於 Github Pages 和 Jekyll 的關係，官方文檔是個不錯的開始。

本文研究以下需求所涉及的知識：

1. 改善 SEO 並增加頁面功能
2. 儘可能少地在倉庫裏增加代碼文件
3. 儘可能少地依賴 Github 與 Jekyll

Jekyll 項目結構

一個較簡單的 Jekyll 項目的文件結構如下：

.
├── _config.yml
├── _posts
│   └── 2020-03-14-jekyll-behind-github-pages.md
├── about.md
├── readme.md
├── _layouts
│   ├── default.html
│   ├── post.html
│   └── page.html
└── _includes
    ├── footer.html
    └── header.html

• 配置文件：/_config.yml
• post：格式為 /_posts/YYYY-mm-dd-title.md 的文件，將被渲染為網頁 /YYYY/mm/dd/title.html
• 索引頁：任一目錄中都會依次查找使用 index.md 或 readme.md 用以生成 index.html。比如 /foo/readme.md 對應網頁的路徑為 /foo/index.html，甚至訪問 /foo 也可以
• 其它頁：如 about.md。Github Pages 會將所有非下劃線開頭的路徑中的 markdown 文件轉為對應名字的網頁。

• 網頁模板：使用 Liquid 編寫的模板文件（就是帶 {% if true %} {{ var | filter }} {% endif %} 一類標記的 html 或 markdown）

  • layout：/_layouts/ 裏是 layout 模板。markdown 文件的內容會嵌入到以下 layout中作為最終的網頁：

    1. /index.md 或 /readme.md 依次嘗試 home.html、page.html 和 default.html
    2. post 會依次嘗試 post.html 和 default.html
    3. 其它 markdown 文件依次嘗試 page.html 和 default.html
  • 組件：/_includes/ 通常是 layout 中抽取出的公共部分，在 layout 中通過如 {%include footer.html %} 引入

網頁模板中的變量

page: Markdown 的元信息

雖然 Jekyll 要求 markdown 文檔開頭要有 Front Matter（即首尾各一行 --- 的 yaml 片段），如：

---
title: "My Real Title"
my_diy_var: "my_diy_value"
---
# My Fake Title

blah blah

等價於如下 yaml 對象：

title: "My Real Title"
my_diy_var: "my_diy_value"
content: "<h1> My Fake Title </h1> <p> blah blah </p>"

該對象在 layout 中名為 page，於是可以這樣用：<h1> {{ page.title }} </h1>{{ page.content }}

但實際上，在 Github Pages 中可以沒有 Front Matter，title 等字段可以從文檔中推斷出來。

注：其它文件如 html、sass 等開頭也可以加 Front Matter，但意義不大。

site: 網站元信息與數據文件

另一個 layout 中可用的重要變量是 site，內容如下：

1. _config.yml 中的字段，例如 site.twitter_username

2. 下劃線開頭的一級目錄（/_*/）中的元信息或數據文件，例如

   1. /_data/ 中的 markdown/yaml/json/csv/tsv 可以用 site.data 遍歷
   2. /_authors/roy.json 可以用 site.authors.roy 得到
3. 所屬代碼倉庫的基本信息，如 site.title 默認是代碼倉庫的名字

使用現成的 Jekyll 主題

我之前的用法是不做任何主題的定製，除了自己寫的簡陋索引頁外只有 markdown 文檔，詳情參見 Code Less, Talk More。

也可以在倉庫 settings 中選擇 官方支持的主題，比如選 minima。這等價於在 _config.yml 中配置 theme: minima

或者可以在網上找個自己滿意的 Jekyll 主題，比如 minimal-mistakes，就下載到本地或在 _config.yml 中配置 remote-theme: mmistakes/minimal-mistakes

本地使用 Jekyll

Jekyll 是一個 ruby 包，安裝需要使用 ruby 自帶的包管理器 gem。

# 在 MacOS 用 brew 安裝 ruby
brew install ruby
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 用 gem 安裝 jekyll 與官方建議的 bundler
# 但因 MacOS 系統限制需要用 -n 綁定執行程序的路徑，否則安裝後找不到可執行文件
gem install -n /usr/local/opt/ruby/bin jekyll bundler

# 在當前路徑下初始化一個項目
jekyll new blogtest

# 在本地安裝依賴並運行服務
cd blogtest
bundle install
jekyll serve

初始項目本身比較簡單，_config.yml 中看到使用的主題是 minima。

可以使用 bundle info minima 找到本地的 minima 代碼，或者在 minima 的 Github 倉庫 下載，以此為起點學習或做點定製開發。

其它資源

• 我的博客現狀
• 原載於我的 wiki