使用Jekyll + Github Pages搭建靜態網站

今天折騰 hugo + stack 主題翻車了，然後就想着試試用Jekyll來搭建個人博客。

Jekyll 是 Github Pages 官方支持的靜態網站生成工具，優點是在可以直接github上編輯md，提交後，github會承擔生成html的工作。而使用hugo等工具，需要先在本地將md文件渲染成html，然後上傳。

hugo的優點是快！

看了幾個jekyll主題，發現 chirpy 最得我心。cotes2020/jekyll-theme-chirpy: A minimal, responsive, and powerful Jekyll theme for presenting professional writing (github.com)

本文記錄Jekyll和chirpy的搭配使用。

安裝Ruby和Jekyll

jekyll也很麻煩，要安裝的東西一大堆：

Follow the instructions in the Jekyll Docs to complete the installation of Ruby, RubyGems, Jekyll, and Bundler.

1. Download and install a Ruby+Devkit version from RubyInstaller Downloads. Use default options for installation.

2. Run the ridk install step on the last stage of the installation wizard. This is needed for installing gems with native extensions. You can find additional information regarding this in the RubyInstaller Documentation

   第一次接觸ruby，完全懵逼，不知道裝了些啥，接近1個GB。打印的日誌是清新脫俗。

3. Open a new command prompt window from the start menu, so that changes to the PATH environment variable becomes effective. Install Jekyll and Bundler using gem install jekyll bundler

4. Check if Jekyll has been installed properly: jekyll -v

到這裏，本地環境就安裝好了。

Chirpy主題的使用

Install

Creating a New Site

跟着這裏操作。簡言之，使用其提供的 template repo 創建自己的 repo，命名爲<GH_USERNAME>.github.io。

Installing Dependencies

將創建的 repo（<GH_USERNAME>.github.io） clone 到本地，執行：

git clone [email protected]:<GH_USERNAME>/<GH_USERNAME>.github.io
cd <GH_USERNAME>.github.io
bundle

依賴安裝完後，生成一個Gemfile.lock文件。

<GH_USERNAME>.github.io裏面有一個Gemfile文件，它指定了你想要使用的gem的位置和版本。

bundle命令根據Gemfile文件安裝依賴，並將安裝的每個依賴的版本，記錄在Gemfile.lock文件裏。這樣，當相同的庫或是項目在另一臺機器上加載時，運行bundle install將安裝完全相同的版本，而不是最新的版本。(在不同的機器上運行不同的版本可能會導致測試失敗等等)。簡單來說就是保證在不同環境下gem版本相同。

Gemfile.lock文件可以提交到github，讓github pages的deploy 腳本也使用相同的版本。但是，由於我是在Windows上運行bundle的，github pages的部署環境是linux。因此，需要運行以下命令，將 x86_64-linux 平臺的一些庫添加到Gemfile.lock裏面（只有幾個，多數是跨平臺兼容的）：

bundle lock --add-platform x86_64-linux

Configuration

主要就是修改如下幾個文件：

_config.yml

timezone: Asia/Shanghai
google_site_verification: googledxxxxxxx.html # 去Google Search Console申請，用於google收錄
avatar: assets/img/avatar/wy-avatar-339x335.jpg # 頭像
comments:
  active: utterances # 使用github issue作爲文章的評論系統
  utterances:
    repo: whuwangyong/whuwangyong.github.io        # <gh-username>/<repo>
    issue_term: title  # < url | pathname | title | ...>
paginate: 20

_tabs/about.md

自定義“關於我”的內容。

favicon

自定義網站圖標。將favicon.ico文件放入assets/img/favicons/。Customize the Favicon - Chirpy (cotes.page)

_data/share.yml

配置文章的分享選項，如Facebook、微博之類的。

Writing a New Post

Writing a New Post | Chirpy (cotes.page)

• 在_posts目錄下創建YYYY-MM-DD-TITLE.md文件即可，必須按照此格式命名。可以使用子目錄，用於分類
• 圖片必須放在/assets/下。最佳實踐：放在/assets/img/posts/[YYYY-MM-DD-TITLE]目錄下

Front Matter

---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT # 2022-01-01 13:14:15 +0800 只寫日期也行；不寫秒也行；這樣也行 2022-03-09T00:55:42+08:00
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]     # TAG names should always be lowercase

author: # 不寫默認就是自己
  name: Full Name
  link: https://example.com

# 以下默認false
math: true
mermaid: true
pin: true
---

分類

支持多層級。如categories: [Java, Spring, AOP]，最終的分類效果是Java/Spring/AOP，這樣就可以複用筆記軟件裏面設置好的分類。

標籤

該主題的作者建議，TAG names should always be lowercase。我猜測這麼做的原因是，大小寫混用會導致相同含義的標籤以多種形式出現，如：VSCode、VScode、vscode。學到了。在我的筆記軟件裏面，大小寫混用的標籤正讓我苦不堪言。

img_path

當文中很多圖片具備共同的前綴時，可以將該前綴提取出來，放在Front Matter。

Liquid Codes

舉例：如果你在正文中添加如下內容，則會輸出該文章的標題。

{{ page.title }}

更多參考：Liquid 模板語言中文文檔 | Liquid 中文網 (bootcss.com)

Running Local Server

You may want to preview the site contents before publishing, so just run it by:

bundle exec jekyll s

After a while, the local service will be published at http://127.0.0.1:4000 .

Deployment

Deploy by Using Github Actions。直接提交到github即可。

Upgrading

如前文所述，依賴的庫及其版本都指定在Gemfile 裏面，因此，修改此文件，更新jekyll-theme-chirpy的版本號即可：

- gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
+ gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"

And then execute the following command:

bundle update jekyll-theme-chirpy

As the version upgrades, the critical files (for details, see the Startup Template) and configuration options will change. Please refer to the Upgrade Guide to keep your repo’s files in sync with the latest version of the theme.

發佈時間與更新時間

chirpy主題還有個優點：自帶文章的更新時間。
​
這就不需要倒騰額外的jekyll插件去實現這個功能了。如gjtorikian/jekyll-last-modified-at: A Jekyll plugin to show the last_modified_at time of a post. (github.com)

添加tab到左側欄

如新增“友情鏈接”tab。在_tabs目錄下新建links.md:

---
title: 友情鏈接
icon: fas fa-link
order: 5
---

調整order和icon。icon去Font Awesome Icons裏面找。然後修改_data/locales/en.yml和_data/locales/zh-CN.yml，在tabs:下添加links: Links和links: 友鏈，以適配中英文。

進階內容

用了兩天，對Jekyll + Github Pages 的工作邏輯有了一些理解。

爲什麼使用Jekyll可以直接提交md

在<github_username>.github.io根目錄下，查看.github/workflows/pages-deploy.yml文件：

name: 'Automatic build'
on:
  push:
    branches:
      - main
    paths-ignore:
      - .gitignore
      - README.md
      - LICENSE

jobs:
  continuous-delivery:

    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0  # for posts's lastmod

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.7
          bundler-cache: true

      - name: Deploy
        run: bash tools/deploy.sh

該文件定義了一個workflow：當push代碼到main分支時，執行jobs裏面定義的動作。最關鍵的是Deploy這一步，它執行了一個腳本：tools/deploy.sh。這個腳本做的事情，就是執行bundle exec jekyll build -d _site將md文件編譯爲html，生成靜態網站，然後將_site下的內容push到gh-pages分支。到這裏就很清楚了，是github幫助我們執行了build操作，將md轉換成了html。

在github上查看你的github.io項目，在Actions下面可以看到每次提交新文章時觸發的workflows：
​
第一個workflow就是上面提到的.github/workflows/pages-deploy.yml，第二個是github pages創建的，可以看到bot標誌。點進workflow runs，可以看到執行的日誌，根據日誌能更加清楚的知道背後的流程。

如果使用hugo建站，github後臺並沒有hugo的環境，所以不能幫助我們編譯md。這就需要我們自己編譯好html，然後push到github.io項目。push之後的流程是一樣的：由github pages的bot將編譯好的靜態網站發佈到https://<username>.github.io。

自定義workflow

• 以修改tools/deploy.sh 以修改`tools/deploy.sh`，在裏面加入自己的操作。如：將sitemap提交到百度資源平臺。
• 在tools目錄下新建腳本，然後在.github/workflows/pages-deploy.yml裏面調用
• 在.github/workflows/下創建新的workflow

第一個親測可行，後兩個還沒研究。

netlify、vercel是什麼

除了github pages，還有netlify、vercel等也能生成並部署靜態網站。它們從<username>.github.io 的main分支拉取md源文件，然後在自己的資源上運行bundle jekyll exec build，將build之後的html放在它們自己的服務器上，並提供一個域名供你訪問這個靜態站點。
除了Jekyll，它們還支持Hugo、Hexo、Next.js等多種靜態網站構建工具。也就是說，只將github作爲一個代碼託管平臺，裏面可以放Jekyll、Hugo等多種構建工具和md文件，netlify和vercel都可以將它們編譯爲html併發布出去。從這個方面說，它們比github強大。

Jekyll的Markdown處理器

Jekyll默認的Markdown Processor是kramdown，這與我們常使用的typora、vscode的md解析器不同。kramdown會將pipe字符|解析爲table語法。如果正文中有link或者image語法，且文本包含了|字符，需要對其進行轉義。下述這種寫在代碼塊裏面可以，如果寫在正文，就會當成表格了。

[A | B](http://foo.com)
[img | 1](http://img.com/1.jpg)

這個問題2014年就有人提了，但是作者一直沒修復：

1. Pipes inside image alt text lead to unwanted table output · Issue #135 · gettalong/kramdown (github.com)
2. the conditional probability equation doesn't display normal · Issue #46 · gettalong/kramdown (github.com)
3. Kramdown bug - pipe character in Markdown link creates a table · Issue #2818 · jekyll/jekyll (github.com)
4. markdown - How do you disable tables in Kramdown? - Stack Overflow
5. 對 Markdown 渲染引擎 kramdown 的幾點 hack | 明無夢 (dreamxu.com)
6. Table syntax · Issue #151 · gettalong/kramdown (github.com)
7. Pipe characters in text creates table · Issue #317 · gettalong/kramdown (github.com)
8. Bug - pipe character in Markdown link creates a table · Issue #431 · gettalong/kramdown (github.com) 這是2017年的issue，作者回復說2.x版本會修復，但仍然存在。在kramdown - syntax頁面，搜索“Automatic and Manual Escaping”可以查看kramdown所有（可能）需要轉義的字符。

所以，如果要繼續用kramdown，要麼禁用table語法，要麼把所有用到|的地方全部轉義。這兩個我都不會選：不用table不可能；爲了適應kramdown修改標準的md語法更不可能。

更改Jekyll的markdown處理器

鑑於kramdown的上述問題，我嘗試給Jekyll換一個Markdown處理器。根據文檔Markdown Options - Jekyll，除了kramdown，Jekyll還支持jekyll-commonmark和jekyll-commonmark-ghpages。我分別試用了這兩個處理器，問題更多。尤其是jekyll-commonmark-ghpages，其兼容的jekyll版本是3.9.x，與我使用的Chirpy主題（需要jekyll 4.x）不兼容。jekyll-commonmark倒是解決了|的問題，但是代碼高亮有問題，有些代碼始終無法渲染，花了整整一天翻遍了github也沒找到jekyll-commonmark到底應該怎麼配置。不負責任的說一句，這就是個坑。

Jekyll也支持自定義處理器，我沒嘗試。另一個優質主題jekyll-TeXt-theme同樣用的kramdown。看來用Jekyll就避免不了kramdown。

搜索功能

Chirpy主題的作者在這裏提到，他使用的是Simple-Jekyll-Search實現的搜索功能。效果不錯，速度飛快。

提交到谷歌/百度等搜索引擎

顯示閱讀量

Reference

1. Getting Started | Chirpy (cotes.page)
2. https://blog.csdn.net/qq_38534524/article/details/108462825

---

本文同步發佈於：

• https://whuwangyong.github.io/2022-03-29-jekyll/
• https://whuwangyong.netlify.app/2022-03-29-jekyll/
• https://whuwangyong.vercel.app/2022-03-29-jekyll/