定制jekyll主題以及github pages部署完全總結

寫在前面

去年就已經開始折騰了jekyll+GitHub Pages的個人站點搭建, 一直以來的想法是自己從零開始進行前端網頁的配置, 出發點是好的, 但是我發現最近已經沒有時間讓我折騰這些了.

恰好前階段看到網上有人使用jekyll的主題進行部落格的配置, 正好省去了自己寫css的複雜手續. 下面來看看如何一步步使用主題進行配置, 以及一些實作的小細節, 希望能幫到準備采用jekyll/GitHub pages進行部落格搭建的你~

雖然依舊走了很多彎路, 但是已經逐漸熟悉了jekyll首頁的配置方法. 真是應了那句老話, “紙上談來終覺淺, 絕知此事要躬行”…

本文不列出具體的配置方法, 具體方法都在對應的參考文獻中, 非常詳細.

主題的搭建與配置(通過gem)

這裡我選擇了jekyll-TeXt-theme這個主題, 主要是從這篇部落格​​1​​​中獲得了靈感, (這是一款低代碼的主題), 話不多數, 當然是先找這個主題的官方文檔​​2​​

接下來就是一步一步順着文檔的思路往下走, 這裡我想體驗一下采用​

​ruby​

​​的​

​gem​

​進行編譯和釋出的方法, 感覺實作起來不算難, 但是這卻成了我折騰到晚上三點的一大絆腳石…

下面主要說通過​

​gem​

​​以及​

​bundle​

​的方式進行主題配置與釋出的方法.

看過我之前文章的話, 配置這個主題應該就很簡單了, 需要注意的一點就是最後關于主題的選擇方面, 直接通過官方文檔中的改寫​

​_config.yml_​

​檔案的方法并不成功, 每次都會顯示github action 編譯失敗(但是在本地的執行不會出現問題), 總是提示找不到主題, 我再三确認, 往上各種找解決方案都是不行… 最後我通過修改主題為遠端主題成功解決了這個問題.

這裡先修改​

​_config.yml​

​檔案,

## !USE TEXT THEME
# theme: jekyll-text-theme # Gem-based Jekyll Themes
remote_theme: kitian616/jekyll-TeXt-theme # Jekyll Remote Theme, see https://github.com/benbalter/jekyll-remote-theme for more information.      

最後加上一行:(提示使用遠端主題插件)

plugins:
  - jekyll-feed
  - jekyll-paginate
  - jekyll-sitemap
  - jemoji
  - jekyll-remote-theme # 添加這一行      

這樣配置的話還需要在​

​gemfile​

​裡面加上對應的插件, 具體gemfile如下:

source "https://rubygems.org"

# gem "jekyll-text-theme", path: "../"
gem "jekyll-text-theme"

gem "tzinfo-data"
gem "wdm", "~> 0.1.0" if Gem.win_platform?

gem "webrick", "~> 1.7"
gem "jekyll-remote-theme"      

改好之後先在同級目錄下執行

bundle install      

然後就能通過

bundle exec      

運作起本地jekyll服務, 在浏覽器輸入​

​localhost:4000​

​就能看到自己的站點了.

給網頁添加圖示

終于搭建好了網站并釋出在了github上, 但是這時候卻出現了一個小小的問題, 網頁标簽頁左邊的小圖示不見了, 取而代之的是一個預設的圖示… 這讓有強迫症的我十分不爽, 于是接下來我們繼續研究如何添加圖示.

同樣地, 我們先進入官方文檔​​3​​找找, 在這裡面還真有很多有價值的資訊~

大緻配置方法就是先進入一個生成ico的網站(​​RealFaviconGenerator​​​), 然後建立​

​_includes/head/favicon.html​

​檔案, 裡面寫入

<!-- start favicons snippet, use https://realfavicongenerator.net/ -->
<link rel="apple-touch-icon" sizes="180x180" href="/src/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/src/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/src/favicon-16x16.png">
<link rel="manifest" href="/src/site.webmanifest">
<link rel="mask-icon" href="/src/safari-pinned-tab.svg" color="#5bbad5">

<!-- 下面兩行用于生成首頁标簽頁以及子網頁标簽頁上面的小圖示 -->
<link rel="shortcut icon" href="/src/favicon.ico" type="image/x-icon"/>
<link rel="bookmark" href="/src/favicon.ico"/>

<meta name="msapplication-TileColor" content="#da532c">
<meta name="theme-color" content="#ffffff">
<!-- end favicons snippet -->      

注意這裡我在部落格站點的根目錄建立了一個​

​src/​

​目錄, 在裡面存放了有上述網站生成的所有icon檔案(png,svg等).

關于數學公式

對于數學公式的支援來自​

​mathjax​

​​, 這款渲染引擎可以對整篇文章進行公式渲染(參考了部落格​​4​​​, 但是美中不足的一點就是其在行内公式中反斜杠仍然表示轉義字元, 這就使内公式中使用諸如​

​\\​

​​這樣的字元的話, 其HTML頁面就隻會顯示一個​

​\​

​​, 這個問題現在也沒有得到解決, 隻能采用折中辦法, 即采用​

​\\\\​

​來表示換行. 當然, 不在行内公式中寫矩陣之類的大符号其實也是一個辦法.

其實不僅是在數學行内公式中, 對于一般的md檔案, 如果寫入字元​

​|​

​​, 其渲染引擎會将其自動識别為表格分隔符, 要解決這個問題隻需在​

​|​

​​前面加上一個​

​\​

​.

從github遷移鏡像到gitee

又是很大的一塊内容… 這裡主要的技術支援是​

​GitHub Actions​

​​, 以及​

​gitee pages​

​.

這裡我主要參考了​​5​​, 裡面的方法真的是非常詳細, 但是最後我還是沒有采用這個方法, 有以下兩個原因:

1. 這個action的作用是将github所有的庫都同步到gitee的, 但是由于github pages的庫名稱是​

   ​xxx.github.io​

   ​, 而gitee的是與使用者名同名的倉庫, 這就導緻其同步之後不能達到完全自動化的目的.
2. 之後推出新版本能夠通過建構兩個倉庫之間的mapping來實作不同名稱倉庫的同步, 但是新的問題又出現了, gitee pages在同步之後不能自動更新頁面, 反而還得自己手動進入​

   ​服務​

   ​​->​

   ​gitee pages​

   ​​->點選​

   ​更新​

   ​才行, 這就是個很大的麻煩事了.

遇到了這樣的問題, 當然是接着尋求搜尋引擎的幫助.

一開始看到的一些網上的方法, 大多采用的是一個名為​​puppeteer​​​的前端自動化子產品, 但是這樣的方法還不是很友善, 畢竟網頁結構發生變化的話又要重新debug, 随後在一篇文章的評論下面看到了一個github項目, 名為​

​gitee-pages-action​

​​​6​​, 通過其官方readme檔案, 一步一步配置, 我就完成了部落格同步的最後一步了, 即鏡像同步到gitee并更新gitee pages.

具體的方法請見​​6​​​或者action首頁​​7​​.

這個方法雖然是通過模拟登陸的方式進行更新的, 但是也已經相當好用了, 成功更新之後會有gitee公衆号的登陸提示. (在送出之後會進行事件觸發, 直接進行同步更新, 在此期間gitee的站點會顯示404)

檔案結構

(這裡是上傳github倉庫的檔案結構,不是本地配置的)

.
├── .github
│   └── workflows
│       └── gitee-mirror-pages.yml // 配置actions
├── 404.html // 404時候顯示的頁面
├── Gemfile // 用于安裝gem的配置檔案
├── _config.yml // 主配置檔案
├── _data //一些配置檔案
│   └── locale.yml 
│   └── ...
├── _includes // 這裡可以修改網頁結構
│   └── head
│       └── favicon.html  // 用于修改圖示的顯示
├── _posts // 部落格的Markdown源檔案存放目錄
│   └── ...
├── src // 部落格的圖示,音頻,圖檔等資源檔案
│   └── ...
├── about.md // `關于`頁面
├── archive.html // 歸檔頁
└── index.html // 站點首頁      

最後的總結

經過了差不多一個禮拜的各種折騰, 我終于完美地實作了部落格的搭建配置與同步, 即實作了如下的功能:

1. 通過​

   ​gem​

   ​部署github pages, 采用jekyll的主題;
2. (在原有的TeXt主題的基礎上, 進行了一些小的修改);
3. 實作了github pages到gitee pages的同步推送與重新整理;

為了完成個人站點的配置, 我經曆了下面的幾個階段:

從一開始的想要自己從零開始配置部落客題, 到開始使用jekyll的官方主題, 在配置過程中采用了輕量化的部署方式(采用ruby gem), 但是這也花費了不少時間, 最後才用遠端主題的方式成功build了github pages. 當然, 這其中也包括很多小細節的實作, 如檔案目錄的寫法, 網頁标簽頁的圖示顯示等.

後來進入部落格的過程中發現github的頁面速度有點慢, 于是我想通過gitee的同步來加速, 這裡用到了github actions的技術(依舊, 從直接導入, 慢慢轉變成指定映射關系之後進行的同步, 省去了很大的功夫).

然後因為推送到gitee的gitee pages沒辦法自動同步(隻能每次推送之後手動點選更新, 自動更新是企業版的功能), 就去尋找網上大佬們的解決方案, 一開始看到的是通過​

​js​

​腳本的方式每次送出之後就進行點選更新(這個方法可以, 但是穩定性會差點), 後來我開始采用gitee-pages-actions的方法(也是github上面的一個開源項目, 本質上還是github actions), 一點一點完善了自己的部落格.

gitee pages在頁面渲染方面還是不如github pages的, 一些HTML文法就不能正常顯示(如圖檔).

最後, 引用一篇部落格​​5​​中提到的:

通過發現問題也借此了解了很多知識，github竟然還有Action這麼神奇的功能，感覺很有趣。回想起之前隻會git clone就太狹隘了。有時間還是要多多了解這些東西，以及背後的原理。任何事物的出現和發展都是有其必然原因和規律。就像偉大的git誕生一樣。（這樣說突然想學習一下程式的曆史，給自己挖個坑有空了解一下，也可以用自己的語言寫一篇曆史故事，感覺會蠻有趣。 - - ）

一個産品的本質就是有需求才會推動實作，而為了實作需要嘗試很多方法，學習很多知識。

我料想，人生也應如是。

主要參考

1. ​​我的Jekyll部落格 | 開放筆記 (goooooouwa.fun)​​​; ​​↩︎​​
2. ​​快速開始 - TeXt Theme (tianqi.name)​​​; ​​↩︎​​
3. ​​Logo 和 Favicon - TeXt Theme (tianqi.name)​​​; ​​↩︎​​
4. ​​關于部落格搭建過程的一些總結和吐槽 | Sharzy​​​; ​​↩︎​​
5. ​​yanglbme/gitee-pages-action: 🤖 Auto Deploy Gitee Pages With GitHub Actions | 無須人為幹預，由 GitHub Actions 自動部署 Gitee Pages​​​; ​​↩︎​​ ​​↩︎​​
6. ​​Gitee Pages Action · Actions · GitHub Marketplace​​​; ​​↩︎​​