前言

原本 Jekyll 使用的是 Layon 主題，想著一開始用極簡主題就好，有需要什麼功能再額外加上去。結果東加西加，網站的程式碼變得很雜亂，不如直接換一個主題。

後來想起之前看過朋友用 Hexo 架的網站看起來滿漂亮的，可以調整的設定不少，也支援 Markdown。因此打算從 Jekyll 轉換到 Hexo，同時作為一個新的開始。

以下內容主要參考官方文檔，記錄自己安裝及配置的過程，Butterfly 相關配置在官方文檔都有詳盡的說明，此篇文章只紀錄部分較特別的設定。

安裝

安裝 Hexo 前需要先安裝 Node.js （核心部分） 與 git （用於推送網頁）。

有了 Node.js 後就可以在終端機執行安裝指令：

npm install -g hexo-cli

建立一個資料夾作為 blog 的根目錄，進入該目錄後配置基本檔案：

cd <folder>
hexo init
npm install

安裝完後資料夾內的結構應該會長這樣：

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

此時基本配置就完成了。

選擇主題

第一件事當然是要選擇一個順眼的主題，預設的主題是 NexT，我選擇的是 Butterfly 主題。除了好看以外，它的官方文檔還是中文的，對我這種英文苦手的人來說非常友好。

由於不同主題的配置不盡相同，因此更換主題時可能無法完美轉移。

安裝過程可直接參考 butterfly 的官方教學。

開始寫文章

在根目錄中輸入以下指令會自動在 source/_posts/ 建立一個新的 Markdown 檔案：

hexo new [layout] <title>

layout 就是文章的初始佈局，存放在 scaffholds 資料夾中。以 post.md 為例，打開可以看到

post.md
---
title: {{ title }}
date: {{ date }}
tag:
---

這個以 --- 分隔的區塊可以當作是個別頁面的設定檔，以下是常用的變數：

  • title 標題 （預設為檔名）
  • data 檔案建立日期
  • updated 檔案修改日期
  • tags 標籤
  • categories 分類

分類與標籤

在 Hexo 中，分類的順序代表階層性，標籤則沒有差別。例如分類 Foo, Bar 表示文章屬於 Foo 分類下的 Bar 分類，一個頁面可以同時擁有多個分類與標籤：

categories:
    - [Sports, Baseball]
    - Diary
tags:
    - Injury
    - Shocking

修改預設檔案名稱

當文章數量逐漸增加時，全部塞在同一個資料夾找起來會很困難，因此想找一個能照年份分類的方法。

如果直接在 source/_posts/2023 裡建立文章，預設產生的文章連結會是 https://jhtnt.github.io/2023/01/11/title。如果想讓文章連結只有標題，例如 https://jhtnt.github.io/posts/title，可以如下修改 _config.yml 的配置。

_config.yml
permalink: posts/:name/
new_post_name: :year/:title.md

permalink 指的是文章的永久連結，new_post_name 則是使用指令新增文章時產生的檔名，以下是幾個常用的變數：

  • :title 文章標題
  • :name 文章檔名
  • :year 文章建立年分 （4 位數）
  • :month 文章建立月分 （2 位數）
  • :day 文章建立日期 （2 位數）

本地預覽

有時我們會需要在正式部署前預覽網頁，這時可以使用 Hexo 的指令。

generate

輸入 hexo generate 或 hexo g 可以生成靜態檔案，加上 -w 或 --watch 可以持續監看並即時生成檔案。

hexo generate
hexo g -w

serve

hexo server 或 hexo s 可以啟動本機伺服器，預設 port 為 http://localhost:4000/。若與其他應用程式的 port 衝突，可以使用 -p 或 --port 來自訂 port。

hexo serve
hexo s -p 4001

在 server 啟動期間會持續監測檔案，效果與 hexo g -w 相同。不過似乎與 Jekyll 一樣只會監測 source/ 裡的資源，若更改了 _config.yml 等檔案需要重新啟動伺服器才會生效。

clean

hexo clean

可以清理快取檔案 (db.json) 和已產生的靜態檔案 (public/)。

若不需要下面的設定，想要直接部署，可跳至 部署到 GitHub Pages

自訂漸層背景

在 _config.butterfly.yml 中有一項設定是 background，可以設定網站的背景，研究後發現可以使用漸層顏色，於是在 WebGradients 找了一個喜歡的顏色貼進設定裡：

_config.butterfly.yml
background: "linear-gradient(120deg, #fbc2eb 0%, #a6c1ee 100%)"

但當我切換成暗色模式後馬上發現不對勁，由於這個主題的暗色模式會對所有顏色加上一層透明度 70% 的黑色，雖然能減少亮度的刺激，卻導致原本的漸層變得很奇怪，於是我決定寫一個 CSS 檔案覆蓋主題的設定。

新增自訂 CSS 檔案

為了避免在更新主題時意外覆蓋掉自訂的檔案，將檔案放在根目錄的 source/ 而不是主題目錄的 source/ 會是比較好的選擇。

首先在建立一個存放 CSS 的資料夾 source/css/ 在裡面建立 custom.css （檔名沒有限制）。然後進入 _config.butterfly.yml 找到 inject 並修改 （有兩個不同的 inject，請看註解辨別）：

_config.butterfly.yml
# Inject
# Insert the code to head (before '</head>' tag) and the bottom (before '</body>' tag)
# 插入代碼到頭部 </head> 之前 和 底部 </body> 之前
inject:
  head:
    # - <link rel="stylesheet" href="/xxx.css">
    - <link rel="stylesheet" href="/css/custom.css">
  bottom:
    # - <script src="xxxx"></script>

這樣就會在每個頁面的 <head> 導入這個檔案。

修改背景顏色

說回剛剛的背景顏色，找了很久發現是受下面這段 CSS 影響，最終我把透明度調成 50%，在不會過亮的情況下還不至於太奇怪。

custom.css
[data-theme='dark'] #web_bg:before {
    background-color: rgba(0, 0, 0, 0.5);
}

改完之後又出現一個問題，文章內部的背景還是黑色的，看起來有點突兀，於是讓它變成有點半透明的效果：

custom.css
#recent-posts>.recent-post-item {
    background: rgba(0, 0, 0, 0.15);
}

.layout>#post {
    background: rgba(0, 0, 0, 0.15);
}

#aside-content .card-widget {
    background: rgba(0, 0, 0, 0.15);
}

最後將 footer 變成透明的就成功讓整體顏色一致了：

custom.css
#footer {
    background: rgba(0, 0, 0, 0);
}

[data-theme='dark'] #footer:before {
    background: rgba(0, 0, 0, 0);
}

自訂程式碼 highlight 主題

Hexo 內建提供 highlight.js 與 Prism.js 兩種 highlight 方式，預設是使用 highlight.js。但是 Prism.js 對程式碼的分割更加細緻，因此我想改用 Prism.js 順便修改配色。

首先關閉 highlight 並開啟 prismjs：

_config.yml
highlight:
  enable: false
prismjs:
  enable: true

之後在 source/css/ 建立一個 CSS 檔案用於存放 highlight 配色，在這個 github repo 有許多可用於 prismjs 的主題，我選擇的是 VS Code Dark+。接著將你要的主題的 CSS 複製到剛才建立的檔案，並在開頭插入這段 code （xxxxxxx） 表示預設顏色：

/* 新添加的內容
  ------------------------------------- 
  --hl-color                  代碼框字體顔色 【必須】 (把下面.hljs的 color複製到這裏來)
  --hl-bg                     代碼框背景色 【必須】 (把下面.hljs的 background複製到這裏來)
  --hltools-bg: #321a0f       代碼框頂部工具欄背景色 【可選】(如果你關掉了 copy、lang 和 shrink,可不用配置這個）
  --hltools-color: #fff       代碼框頂部工具欄字體顔色 【可選】(如果你關掉了 copy、lang 和 shrink,可不用配置這個）
  --hlnumber-bg: #221a0f      代碼框行數背景色 【可選】(如果已經關掉 line_number,可以不用配置這個)
  --hlnumber-color: #fff      代碼框行數字體顔色 【可選】 (如果已經關掉 line_number,可以不用配置這個)
  --hlscrollbar-bg: #d3af86   代碼框滾動條顔色 【可選】（默認為主題主顔色）
  --hlexpand-bg: #d3af86      代碼框底部展開背景色 【可選】(如果已經關掉 highlight_height_limit,可以不用配置這個)
*/

:root {
    --hl-color: #fff;
    --hl-bg: #1e1e1e;
    --hltools-bg: xxxxxxx;
    --hltools-color: xxxxxxx;
    --hlnumber-bg: xxxxxxx;
    --hlnumber-color: xxxxxxxx;
    --hlscrollbar-bg: xxxxx;
    --hlexpand-bg: xxxxxxx;
}

/* 下面是你所選的配色主題的 CSS */

最後設定好此檔案的 inject 就大功告成了。

_config.butterfly.yml
inject:
  head:
    - <link rel="stylesheet" href="/css/vscode_dark_theme.css">

增加評論系統

我所選擇的系統是 Waline，主要原因是風格比較符合我的喜好，且可以匿名留言。部署過程不算太難，官方文檔有詳盡的教學，此處只簡略描述：

建立資料庫

我使用的資料庫是 MongoDB Atlas，並非 Waline 推薦的 LeanCloud，建立資料庫與下面的變數設定見這篇文章，除了 UI 有些許不同外其餘照著做即可。

部署 Vercel

使用 Waline 文檔提供的連結進入 Vercel 頁面，登入 github 後依照步驟進行第一次部署。然後進入 Setting -> Environment Variables 設定環境變數 （不同資料庫需要設定的環境變數不一樣）。

最後重新部署後取得 server 端位址，若沒有做額外設定連結應為 https://xxxxx.vercel.app，可以先隨意發一則評論測試是否設定成功。

開啟 Hexo 評論設定

先指定使用 Waline，開啟 lazyload 則使用者滾動到評論位置時才會開始加載：

_config.butterfly.yml
comments:
  use: Waline
  lazyload: true

再來設定 Waline，除了 Butterfly 主題提供的幾個選項外，可以在 option 下新增 Waline 的自定義選項。

需要特別注意在自定义语言這頁的選項都屬於 locale 的子選項，寫法可參考下方的範例。
（發現選項沒有生效，研究了好幾個小時才發現原因）

_config.butterfly.yml
waline:
  serverURL: https://xxxxx.vercel.app
  option:
    locale:
      locale:
      mail: 電子信箱
      placeholder: 有任何問題或建議歡迎留言提出 # 評論框默認文字
      sofa: 暫無留言 # 評論區為空時的顯示文字
    imageUploader: false # 上傳圖片功能
    search: false # 搜尋 gif 功能

這樣就設置完成了。

渲染 KaTeX

一開始我使用了官方提供的方法，然而 hexo-renderer-markdown-it 無法成功渲染，而 hexo-renderer-markdown-it-plus 雖然成功了，但沒辦法顯示斜體感覺怪怪的。

最後我找到了這篇文章，安裝 hexo-renderer-markdown-it-katex 後不需要額外設定即可渲染 KaTeX：

npm un hexo-renderer-marked --save # 移除原本的渲染插件
npm i hexo-renderer-markdown-it-katex --save # 安裝新插件

KaTex 測試：Sn=an+d⋅n(n−1)2S_{n} = an + d \cdot {\cfrac{n(n-1)}{2}}

增加搜尋系統

實際過程比想像中簡單，若只採用預設設定，只需要安裝 hexo-generator-search，並啟用搜尋功能即可。

npm install hexo-generator-search --save
_config.butterfly.yml
local_search:
  enable: true

部署到 GitHub Pages

終於將網站都布置好後，就可以準備部署到 github 上了。

首先在 github 上建立一個 repository，名稱必須為 <你的 username>.github.io （全小寫）。

要部署到 github 有兩種方式：

  • GitHub Actions
  • hexo-deployer-git 插件

這裡我選擇比較方便使用的後者，首先安裝此插件：

npm install hexo-deployer-git --save

再來進行 deploy 的設定，注意 url 最後面不要有 /，repo 的部分，如果你的 username 包含大寫，不需要轉成小寫。

_config.yml
url: https://<你的小寫 username>.github.io # 約在 16 行

deploy:
  type: git
  repo: https://github.com/<你的完整 username>/<剛剛建立的 repository 名稱>.git
  branch: gh-pages

最後每次部署前輸入以下指令即可：

hexo clean
hexo generate
hexo deploy

關於進階的部署（自動修改最後編輯時間）可以參考這篇文章。

另存原始檔案

由於 Hexo 部署時所產生的是最終的 html 等檔案，若需要在其他電腦編輯，還是使用原始檔案更方便，因此建議另外開一個 repository 儲存新檔案。

首先在根目錄初始化 git：

git init

然後連結到新的 repository，在 github 頁面可以找到類似下方的指令，在根目錄執行即可連結到 repository：

git remote add origin https://github.com/<username>/<新 repo 名稱>.git
git branch -M main
git push -u origin main

雜項

此處為直接更改到主題檔案的部分，升級後需要重新修改。

在更新主題時，需要先將檔案復原再 pull 新版本的主題：

cd .\themes\butterfly\
git reset HEAD --hard
git pull

  • 取消當滑鼠放到頭像上會旋轉一圈
    link

    aside.styl
    &:hover
transform: rotate(360deg)

Reference