本文已不再于此更新，最新版本請(qǐng)見：xjtu-blacksmith.cn/essay/jekyll-of-pages。

GitHub 與 Gitee 提供的 Pages 服務(wù)中，均內(nèi)嵌了 Jekyll 支持（Gitee 還提供了 Hugo 與 Hexo 支持）。所謂「支持」，即指這些生成工具掛在云端；你只需要提供原始代碼（如 Markdown 文檔、Sass/Stylus/Less 樣式表），再由 Pages 服務(wù)自動(dòng)編譯、部署即可。這樣，搭建網(wǎng)站的技術(shù)門檻進(jìn)一步下降，你只需要會(huì)兩件事就能搭建網(wǎng)站了：

1. 會(huì)寫 Markdown 文檔；
2. 注冊(cè) GitHub 或 Gitee 賬號(hào)，點(diǎn)點(diǎn)鼠標(biāo)，在你的代碼倉(cāng)庫(kù)中啟用 Pages 服務(wù)。

因?yàn)榧夹g(shù)門檻如此之低，導(dǎo)致不少用戶壓根就意識(shí)不到 Pages 服務(wù)內(nèi)置了 Jekyll 工具，甚至以為每一個(gè) Markdown 文檔理所當(dāng)然地就能變成一個(gè)網(wǎng)頁(yè)。此外，另一個(gè)常被忽視的問(wèn)題是：由 Pages 服務(wù)調(diào)用的 Jekyll 工具，并非最新版本，而且隱性地增添了許多插件，這可能使用戶在本地使用 Jekyll 或遷移平臺(tái)時(shí)碰上「不協(xié)調(diào)」的問(wèn)題。最常見的一個(gè)問(wèn)題就是：在 GitHub Pages 上正常生成的代碼倉(cāng)庫(kù)，到 Gitee Pages 上就變得一團(tuán)糟。這不是因?yàn)?Gitee Pages 的功能「不如」GitHub Pages，而是因?yàn)椋?/p>

GitHub Pages 沒(méi)有告訴你它們?yōu)樽约旱?Jekyll 多加了幾個(gè)插件，Gitee Pages 也沒(méi)有告訴你它們的 Jekyll 并沒(méi)有這些插件。

這里對(duì) GitHub Pages 與 Gitee Pages 所使用的 Jekyll 進(jìn)行一個(gè)簡(jiǎn)單的分析（后面姑且簡(jiǎn)稱為 GitHub Jekyll 與 Gitee Jekyll），以說(shuō)明它們隱性地附加了哪些功能，需要特別注意。

Jekyll on GitHub Pages

GitHub Pages 中所采用的 Jekyll 及插件、依賴，被匯總到名為 github-pages 的 Gem 中（主頁(yè)）。如果你在本地安裝了這個(gè) Gem，可以運(yùn)行它來(lái)查看其所要求的各項(xiàng)依賴版本。以目前最新的 204 版本為例，在 shell 中運(yùn)行：

$ github-pages versions
+------------------------------+---------+
| Gem                          | Version |
+------------------------------+---------+
| jekyll                       | 3.8.5   |
| jekyll-sass-converter        | 1.5.2   |
| kramdown                     | 1.17.0  |
| jekyll-commonmark-ghpages    | 0.1.6   |
| liquid                       | 4.0.3   |
| rouge                        | 3.13.0  |
| github-pages-health-check    | 1.16.1  |
| jekyll-redirect-from         | 0.15.0  |
| jekyll-sitemap               | 1.4.0   |
| jekyll-feed                  | 0.13.0  |
| jekyll-gist                  | 1.5.0   |
| jekyll-paginate              | 1.1.0   |
| jekyll-coffeescript          | 1.1.1   |
| jekyll-seo-tag               | 2.6.1   |
| jekyll-github-metadata       | 2.13.0  |
| jekyll-avatar                | 0.7.0   |
| jekyll-remote-theme          | 0.4.1   |
| jemoji                       | 0.11.1  |
| jekyll-mentions              | 1.5.1   |
| jekyll-relative-links        | 0.6.1   |
| jekyll-optional-front-matter | 0.3.2   |
| jekyll-readme-index          | 0.3.0   |
| jekyll-default-layout        | 0.1.4   |
| jekyll-titles-from-headings  | 0.5.3   |
| jekyll-swiss                 | 1.0.0   |
| minima                       | 2.5.1   |
| jekyll-theme-primer          | 0.5.4   |
| jekyll-theme-architect       | 0.1.1   |
| jekyll-theme-cayman          | 0.1.1   |
| jekyll-theme-dinky           | 0.1.1   |
| jekyll-theme-hacker          | 0.1.1   |
| jekyll-theme-leap-day        | 0.1.1   |
| jekyll-theme-merlot          | 0.1.1   |
| jekyll-theme-midnight        | 0.1.1   |
| jekyll-theme-minimal         | 0.1.1   |
| jekyll-theme-modernist       | 0.1.1   |
| jekyll-theme-slate           | 0.1.1   |
| jekyll-theme-tactile         | 0.1.1   |
| jekyll-theme-time-machine    | 0.1.1   |
+------------------------------+---------+

能看到其列出來(lái)一大串的 Gem。通過(guò)這個(gè)頁(yè)面也可以看到 GitHub Pages 上的 Jekyll 版本及相關(guān)依賴。

以上這些 Gem，可以大致劃分為四類：

1. Jekyll 及其依賴，比如 Sass 轉(zhuǎn)換、Kramdown 引擎、Liquid 模板語(yǔ)言、Rouge 高亮器等等。這些算是常規(guī)構(gòu)件，不可或缺。注意，目前 GitHub Pages 使用的 Jekyll 版本為 3.8.5，而最新版本是 4.0.0，有一個(gè)「適當(dāng)」的延遲。
2. 為 GitHub Pages 定制的額外功能，主要有兩個(gè)：jekyll-commonmark-ghpages，在 Commonmark 基礎(chǔ)上改出來(lái)的 GFM 引擎（但 Jekyll 仍然默認(rèn)用 Kramdown）；github-pages-health-check，用于檢查域名（DNS 服務(wù)）和 GitHub Pages 服務(wù)是否正常。
3. 若干 Jekyll 插件，基本上都是 jekyll 開頭。后面會(huì)詳細(xì)分析。
4. 若干 Jekyll 主題，除了 Jekyll 的默認(rèn)主題 minima 和一個(gè)基本主題 jekyll-swiss 之外，還有 13 個(gè) jekyll-theme 開頭的，它們就是你在 GitHub Pages 服務(wù)里即選即用的 13 個(gè)主題。

從以上后三類可以看到，GitHub Jekyll 其實(shí)「加持」了很多的輔助件，并不單純。而這樣多的輔助構(gòu)件，最終營(yíng)造出了前面所提的「每一個(gè) Markdown 文檔理所當(dāng)然地可以變成一個(gè)網(wǎng)頁(yè)」之幻覺。事實(shí)上，如果是純粹用 Jekyll 搭建網(wǎng)站，所需要做的工作仍然是不少的。

下面再詳細(xì)分析一下 GitHub Jekyll 所采用的插件。

Jekyll 的 Markdown 引擎

在 Maruku 停止更新后，Jekyll 的默認(rèn) Markdown 引擎變成了 Kramdown，同樣也是一個(gè)用 Ruby 開發(fā)的工具。Kramdown 實(shí)現(xiàn)了相當(dāng)多的拓展功能，典型者如 LaTeX 公式、行內(nèi)屬性標(biāo)記等，拓展了用 Markdown 實(shí)現(xiàn)網(wǎng)頁(yè)（HTML）的可能性。

GitHub Jekyll 也是默認(rèn)用 Kramdown 渲染 Markdown，不過(guò)前面看到其也提供了一個(gè) GFM 引擎。在 GitHub 的官方文檔中對(duì)此有特別說(shuō)明，并強(qiáng)調(diào)「只有使用后者才能保證網(wǎng)站效果與 GitHub 中（渲染的 Markdown 頁(yè)面）的一樣」。仔細(xì)想想，有這個(gè)需求的用戶應(yīng)該不在少數(shù)。

常規(guī)插件

在 GitHub Jekyll 所用插件之中，下面這些是比較常規(guī)、常見的（強(qiáng)調(diào)者表示默認(rèn)啟用）：

• jekyll-sitemap，用于生成站點(diǎn)地圖文件 sitemap.xml 供搜索引擎抓??；
• jekyll-feed，用于生成 RSS 訂閱鏈接 feed.xml；
• jekyll-coffeescript，CoffeeScript 轉(zhuǎn)換器；
• jekyll-redirect-from，重定向插件，從功能上可以理解為 permalink 的反面；
• jekyll-paginate，分頁(yè)器；
• jemoji，表情包；
• jekyll-avatar，提供了形如 {% avatar [username] %} 的標(biāo)簽，用于獲取 GitHub 用戶的頭像；
• jekyll-remote-theme，使你能夠使用掛在 GitHub 上的 Jekyll 主題；
• jekyll-gist，提供了形如 {% gist xxx %} 的標(biāo)簽，用于在頁(yè)面上展示 Gist 的內(nèi)容；
• jekyll-mentions，使得 GitHub 上的 @ 用戶功能在網(wǎng)站中得到支持；
• jekyll-relative-links，能夠?qū)⒅赶?Markdown 文檔的鏈接轉(zhuǎn)換為指向?qū)?yīng) HTML 頁(yè)面的鏈接（有點(diǎn)雞肋）。

其中許多算是 Jekyll 的標(biāo)配插件，經(jīng)常被使用。它們更多地是提供了一種可選項(xiàng)，不會(huì)對(duì)網(wǎng)站的生成效果有太大影響。

靜默增強(qiáng)插件

除了上面所提的基本插件，另外的插件則非?！戈庪U(xiǎn)」，默認(rèn)啟用，發(fā)揮了一些你根本意識(shí)不到的功能。包括：

• jekyll-seo-tag：定制了 {% seo %} 這個(gè) Liquid 標(biāo)簽的功能。SEO 的其他方面不說(shuō)，網(wǎng)站的 <title> 元素就是它搞定的（使用了 _configs.yml 文件中的 title 和 description 屬性）。所以在用 GitHub Jekyll 時(shí)要想改變網(wǎng)頁(yè)標(biāo)題的格式，就必須要求它停止輸出標(biāo)題：{% seo title=false %}，否則你會(huì)以為標(biāo)題是「無(wú)中生有」的。
• jekyll-github-metadata：用于從 GitHub 獲取元信息，比如項(xiàng)目名稱、作者之類的。它主要是給 GitHub Pages 生成的網(wǎng)站提供一些默認(rèn)參數(shù)，比如上面的 SEO 插件就會(huì)使用 GitHub 倉(cāng)庫(kù)的項(xiàng)目名稱、描述作為網(wǎng)站的標(biāo)題和副標(biāo)題。在本地用 Jekyll 構(gòu)建 Pages 上的網(wǎng)站時(shí)，十有八九會(huì)出現(xiàn)「No GitHub API authentication」的警告，這個(gè)鍋也得由它來(lái)背（它要用 GitHub API 來(lái)獲取這些信息）。
• jekyll-optional-front-matter：根據(jù) Jekyll 的機(jī)制，其只會(huì)轉(zhuǎn)換有 YAML 頭信息（哪怕是空的）的 Markdown 文件，這個(gè)插件則取消了這一要求。所以如果你發(fā)現(xiàn)用在其他場(chǎng)合使用 Jekyll 時(shí)許多 Markdown 文件沒(méi)有被轉(zhuǎn)換，你會(huì)意識(shí)到這個(gè)插件的作用：讓你不用寫頭信息。（另外，這個(gè)規(guī)則對(duì) Sass 文件不使用，所以你得對(duì)自己寫的、放在 _sass 目錄以外的 Sass 文件至少給一個(gè)空的頭信息。）
• jekyll-readme-index：這個(gè)插件使得 Jekyll 在找不到 index.html 或 index.md 時(shí)，將 README.md 轉(zhuǎn)換為 index.html 作為替代。這個(gè)功能的好處在于實(shí)現(xiàn)了 GitHub 頁(yè)面預(yù)覽和網(wǎng)站構(gòu)建的統(tǒng)一，因?yàn)樵?GitHub 頁(yè)面上 README 的作用就相當(dāng)于一般網(wǎng)站的 index.html。
• jekyll-default-layout：幫助你自動(dòng)給首頁(yè)套 layout: home、給推送文章套 layout: post、給一般頁(yè)面套 layout: page、實(shí)在不行就套 layout: default。作用很明顯：讓你不用寫頭信息。
• jekyll-titles-from-headings：自動(dòng)將一個(gè)沒(méi)有指明 title 的 Markdown 文件之首級(jí)標(biāo)題提取為 title。從頁(yè)面顯示來(lái)說(shuō)，一個(gè)頁(yè)面有沒(méi)有 title 其實(shí)無(wú)關(guān)緊要，但需要生成網(wǎng)站導(dǎo)航、文章列表等的時(shí)候就必須確保每個(gè)頁(yè)面都有 title。這個(gè)功能的作用也很明顯：讓你不用寫頭信息。

以上幾個(gè)插件，都是「靜默」生效；其中不少在 Jekyll 中并不默認(rèn)啟用，但它們?cè)?GitHub Jekyll 中全都是默認(rèn)啟用的。它們發(fā)揮的作用，也許你之前從未意識(shí)到，但現(xiàn)在一看即知。

GitHub Pages 主題

GitHub Pages 提供的 13 個(gè)基本主題，也被包含在依賴當(dāng)中，這意味著你不需要安裝就能使用它們。它們?cè)?_configs.yml 中用 theme 屬性啟用（也許這是許多人見過(guò)的第一行 YAML 代碼？），這會(huì)給初學(xué)者造成一種誤解，以為其他的主題也可以這樣通過(guò)一行代碼來(lái)使用。

事實(shí)上，如果要在 GitHub Jekyll 中使用其他主題，有這樣兩種辦法：

1. 啟用 jekyll-remote-theme 插件，這樣你就可以使用任意一個(gè)在 GitHub 上公開的 Jekyll 主題（其他地方的不行）；
2. 把主題下載下來(lái)，將對(duì)應(yīng)文件拷貝到指定位置——注意清理之前的主題。（Jekyll 的主題管理不是很靈活，不如 Hugo、Hexo 等工具。）

當(dāng)然，如果你是在本地生成網(wǎng)站文件后再借 Pages 的服務(wù)器發(fā)布，方法就比較多了。

總結(jié)

經(jīng)過(guò)以上對(duì)各個(gè)依賴的分析，我們可以發(fā)現(xiàn)：GitHub Jekyll 提供了相當(dāng)多的輔助功能，極大的化簡(jiǎn)了網(wǎng)站的生成，而我們甚至還不自知。在不清楚這些背景的情況下，嘗試從 GitHub Pages 服務(wù)下遷移出 Jekyll 項(xiàng)目，很有可能會(huì)踩坑，比如：

• 為什么這個(gè) Markdown 文件沒(méi)有被轉(zhuǎn)換？（因?yàn)槟銢](méi)有寫頭文件，怪 jekyll-optional-front-matter）
• 為什么文章列表里的文章標(biāo)題都是空的？（因?yàn)樗鼈兊臉?biāo)題是正文中的 h1 標(biāo)簽，沒(méi)有寫到頭信息中的 title 里，怪 jekyll-titles-from-headings）
• 為什么這個(gè)路徑下的頁(yè)面不見了？（因?yàn)槟阍瓉?lái)用的是 README.md 轉(zhuǎn)換成 index.html，怪 jekyll-readme-index）

當(dāng)然，問(wèn)題的可能性不多，一一排除總能解決。所以歸結(jié)出一個(gè)結(jié)論：與其花時(shí)間琢磨上面這么多 Gem 的關(guān)系，還不如自己去踩踩坑。

坑歸坑，好話也還是要說(shuō)幾句：如果只是一直用 GitHub Jekyll，以上這些都不算是問(wèn)題，而算優(yōu)勢(shì)?！窶arkdown 文件自動(dòng)變成網(wǎng)頁(yè)」這樣的好事，還是人人所欲的；它畢竟能讓許多完全不了解前端技術(shù)的人構(gòu)建一整個(gè)網(wǎng)站出來(lái)，應(yīng)該算是大好事。

Jekyll on Gitee Pages

Gitee Pages 究竟用的是綠 Jekyll 還是花 Jekyll，沒(méi)有公開信息，只能間接地尋找一些蛛絲馬跡了。

嘗試在一個(gè) Gitee 倉(cāng)庫(kù)中啟用了 Gitee Pages，發(fā)現(xiàn)它支持 jekyll-seo-tag，但在生成的 HTML 頁(yè)面上赫然顯示該插件版本為 2.3.0。經(jīng)過(guò)檢查，這個(gè)版本是 2017 年八月發(fā)布的，看來(lái)有些年頭了。

但是僅從這一個(gè)插件不能推斷出所有信息。為此，我又測(cè)試了其他幾個(gè)插件，發(fā)現(xiàn)：

• jekyll-sitemap、jekyll-feed 兩個(gè)插件都可以正常使用，說(shuō)明它們算是 Gitee Jekyll 的依賴。
• 另外，在 jekyll-feed 生成的 feed.xml 中意外發(fā)現(xiàn)了 Jekyll 的版本信息：3.6.2。檢查發(fā)現(xiàn)這是 2017 年十月發(fā)布的版本。
• jekyll-mentions 插件竟然可以用，指向 GitHub 的用戶主頁(yè)——自己做一個(gè) Gitee 版本的應(yīng)該也挺容易吧？跟 GitHub 有什么關(guān)系？
• jemoji 用不了。
• 幾個(gè)靜默強(qiáng)化插件中，除了 jekyll-github-metadata 未啟用之外，其他的都能正常工作。這造成的后果是，在 Gitee Pages 中必須自己寫 baseurl，否則站點(diǎn)的樣式表就找不著了，鏈接也會(huì)錯(cuò)亂。
• jekyll-remote-theme 居然能用……前提是把 baseurl 寫對(duì)。

根據(jù)以上的分析，可以得出以下幾個(gè)結(jié)論：

1. Gitee Jekyll 的版本很舊了，一整套工具可能只是 2017 年末的「最新版」。找到了 Gitee Pages 的上線說(shuō)明，發(fā)布時(shí)間是在 2018 年年中，差不太遠(yuǎn)（也許前端支持做好之后半年在做后端支持）。
2. Gitee Jekyll 跟 GitHub Jekyll 對(duì)接不良，遷移或同步的話得增補(bǔ)很多信息，并且不少插件用不了。
3. Gitee Jekyll 竟然支持 GitHub 上的遠(yuǎn)程主題，但是用起來(lái)似乎也存在若干問(wèn)題，不穩(wěn)定。

以上三條再歸納為一個(gè)最終的結(jié)論：（目前的）Gitee Jekyll 不可靠。為了用 Gitee Pages，只有在本地生成網(wǎng)站文件再發(fā)布了。和 GitHub Pages 比起來(lái)，這無(wú)疑抬高了使用門檻；這倒不算什么，重要的是在這種情況下 Gitee Jekyll 形同虛設(shè)，不會(huì)有什么人去用了。

冷嘲熱諷不能解決問(wèn)題。剛剛和 Gitee 管理團(tuán)隊(duì)聯(lián)系上，表示將來(lái)會(huì)改進(jìn)這些問(wèn)題。持續(xù)關(guān)注。如果 Gitee Pages 的生態(tài)做出來(lái)了，肯定是也是一件大好事吧！