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

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

提示

1. hugo的優點是快！
2. 雖然github pages只支持渲染Jekyll，但是netlify、vercel等平台支持渲染hugo、jekyll等更多框架。

主題選擇

看了幾個jekyll主題，發現 Chirpy 最得我心。在jekyll-template · GitHub Topics下，Chirpy主題排名第二。

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

安裝Ruby和Jekyll

前面說了github可以編譯Jekyll，為什么還要在本地裝一套環境呢。主要是為了方便調試，尤其是剛開始配置主題的時候。

比起Hugo來說，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 [e-mail]:<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 # serve, server, s      Serve your site locally

# 編譯命令是
bundle exec jekyll b # build, b              Build your site

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，在里面加入自己的操作。如：將sitemap提交到百度資源平台。
• 在tools目錄下新建腳本，然后在.github/workflows/pages-deploy.yml里面調用
• 在.github/workflows/下創建新的workflow

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

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

修改tools/deploy.sh，在里面新增一個函數：在deploy之后，根據生成的 sitemap.xml 創建一個包含所有url的sitemap.txt文件。將該文件提交到百度資源平台。但是GitHub封了百度的爬蟲，可以考慮在vercel上也部署一份，讓百度去爬vercel。另一種方法是使用反向代理，讓百度爬自己的主機，自己的主機去連接github。
至於google和bing，訪問 Google Search Console 和 Bing Webmaster Tools 進行設置，添加博客地址之后就等着爬蟲光臨。
搜狗也可以試一試，GitHub沒封搜狗。

# file_name: tools/deploy.sh
# 新增 submit_sitemap 函數，在 deploy 之后調用
submit_sitemap() {
  echo "------ >>> submit_sitemap ---------"
  grep "<loc>" sitemap.xml | grep -v 'html' | awk -F '[< >]' '{print $3}' > sitemap.txt
  curl -H 'Content-Type:text/plain' --data-binary @sitemap.txt "http://data.zz.baidu.com/urls?site=https://whuwangyong.github.io&token=5os4wCK5ct7kBZRN"
  curl -H 'Content-Type:text/plain' --data-binary @sitemap.txt "http://data.zz.baidu.com/urls?site=https://whuwangyong.vercel.app&token=5os4wCK5ct7kBZRN"
  rm -f sitemap.txt
  echo "------ submit_sitemap <<< ---------"
}

main() {
  init
  build
  # ...
  deploy
  submit_sitemap
}

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語法更不可能。

除了|字符，<>、liquid cldoe語法（{{}}）等也需要轉義：

總之要注意的地方挺多，不能毫無顧忌地寫markdown。

更改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實現的搜索功能。效果不錯，速度飛快。

顯示閱讀量

使用Google Page Views： Enable Google Page Views | Chirpy (cotes.page)

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/