Allen's Blog

User Manual 👉

簡介

本項目是 Fork 自 Hux Blog，在原版的基礎上添加了多項增強功能：

• Mermaid 圖表支援：使用 Mermaid 10.9.0，支援所有圖表類型（流程圖、序列圖、甘特圖、心智圖、時間線、類別圖、Git圖、圓餅圖等圖表）
• LaTeX 數學公式：修復原版顯示問題，完美支援數學公式渲染
• 文章更新時間：支援顯示文章的最後更新時間
• XML Sitemap：SEO 優化的網站地圖，幫助搜尋引擎索引
• 深色模式：完整的深色主題支援，包含對 Fork Awesome 圖標的深色模式適配
• Giscus 評論系統：基於 GitHub Discussions 的現代評論系統，統一配置於 _config.yml，自動適配主題
• Medium Zoom 圖片放大：點擊圖片放大功能，提供優雅的 Medium 風格縮放效果，支援深色/淺色主題
• Fork Awesome 圖標庫：使用 Fork Awesome 1.2.0 替代 Font Awesome，提供豐富的開源圖標支援

本項目通過 Jekyll 在 GitHub Pages 上搭建 Blog 系統。Jekyll 是一個靜態網站生成器（Static Site Generator, SSG），它能將 Markdown、HTML、Liquid 模板等內容轉換成靜態網頁，Jekyll 會將你的文件內容加入你選擇主題的布局樣式中，最後產生屬於你的靜態部落格網站。

透過 Jekyll 建置的網站安全性高，因為沒有資料庫和伺服器端程式碼可被攻擊，透過 GitHub Pages 部署完全免費，且不用擔心 DDoS 攻擊。

Planned Features

Feature	進度
添加深色模式	Done

部署

登錄自己的 GitHub 帳號後 Fork 這個項目。

如何使用 GitHub Pages，如何快速配置請參考：https://youtu.be/YVj3JKMH9p8?si=DZ1mAXQKB6QApnef

更詳細的配置請參考： https://github.com/qiubaiying/qiubaiying.github.io/wiki

要修改以下檔案的內容

• _config.yml 的 Google Analytics tracking ID 替換成你自己的
• head.html 中有一個

<meta name="google-site-verification" content="xBT4GhYoi5qRD5tr338pgPM5OWHHIDR6mNg1a3euekI" />

替換這個 Google Search Console的識別標籤，會影響網站收錄

Giscus 評論系統設定

本項目使用 Giscus 作為主要評論系統，基於 GitHub Discussions 提供互動功能。所有設定已統一到 _config.yml，無需修改 JavaScript 檔案。

1. 修改 _config.yml 檔案

找到 giscus 區塊（約第 69 行），更新為你的倉庫資訊：

giscus:
  repo: your-username/your-repo-name # 替換為你的 GitHub 用戶名和倉庫名
  repo_id: YOUR_REPO_ID # 從 giscus.app 取得的倉庫 ID
  category: Comments # GitHub Discussion 分類名稱
  category_id: YOUR_CATEGORY_ID # 從 giscus.app 取得的分類 ID
  mapping: pathname # 識別文章的方式（建議保持 pathname）
  strict: 0 # 使用嚴格識別模式（0=關閉，1=開啟）
  reactions_enabled: 0 # 啟用 emoji 反應（0=關閉，1=開啟）
  input_position: top # 輸入框位置（top 或 bottom）
  dark_theme: dark_dimmed # 深色模式使用的主題
  light_theme: light # 淺色模式使用的主題
  emit_metadata: 0 # 是否發送元數據
  lang: zh-TW # 介面語言

重要提示：所有 Giscus 設定都在 _config.yml 中完成，系統會自動將這些設定傳遞給 JavaScript。不需要再修改任何 JavaScript 檔案！

2. 設定步驟

1. 前往 giscus.app
2. 輸入你的 GitHub 倉庫（格式：username/repo）
3. 選擇頁面 ↔️ discussions 映射關係（建議選擇「Discussion 的標題包含頁面的 pathname」）
4. 選擇 Discussion 分類（建議新建一個 "Comments" 分類）
5. 複製生成的設定值到 _config.yml 中的對應欄位

3. 倉庫要求

• 倉庫必須是公開的
• 必須安裝 giscus app
• 必須開啟 Discussions 功能（在倉庫的 Settings → General → Features 中啟用）

4. 主題支援

評論系統會自動適配網站的深色/淺色主題：

• 淺色模式：使用 light_theme 設定的主題（預設：light）
• 深色模式：使用 dark_theme 設定的主題（預設：dark_dimmed）
• 即時切換：當使用者切換網站主題時，評論區主題會即時更新

可以在 Giscus 主題預覽 查看所有可用的主題選項。

Medium Zoom 圖片放大功能

本部落格內建 Medium Zoom 圖片點擊放大功能，提供優雅的 Medium 風格縮放效果。

功能特點

• 自動啟用：所有文章中的圖片（Markdown 的 ![]()）都會自動支援點擊放大
• 主題適配：放大時的背景色會根據當前主題自動調整
  • 淺色模式：白色半透明背景
  • 深色模式：深灰色半透明背景
• 即時切換：切換網站主題時，圖片放大的背景色會即時更新
• 輕量級：僅 ~10KB，不影響頁面載入速度
• 零配置：無需在 Front Matter 中額外設定

使用方式

在 Markdown 文章中正常插入圖片即可：

![圖片描述](圖片路徑)

圖片會自動獲得點擊放大功能，點擊圖片即可放大查看，再次點擊或按 ESC 鍵關閉。

技術細節

• 使用 Medium Zoom v1.1.0
• 整合於 post.html 和 keynote.html 兩種布局
• 通過 js/medium-zoom-init.js 初始化並整合主題切換
• 與 js/dark-mode.js 同步，確保主題一致性

Posts

文章存放在 _posts/ 目錄下的 Markdown 文件。 文章的元數據以 YAML 格式的Front Matter列出。 例如，Hello 2015 的Front Matter如下：

---
layout:     post
title:      "Hello 2015"
subtitle:   " \"Hello World, Hello Blog\""
date:       2015-01-29 12:00:00
author:     "Hux"
header-img: "img/post-bg-2015.jpg"
catalog: true
tags:
    - Life
    - Meta
---

注意：tags 部分也可以寫成 tags: [Life, Meta] 的形式。

在引入 Rake 之後，我們可以使用下面的命令來簡化文章創建：

rake post title="Hello 2015" subtitle="Hello World, Hello Blog"

這個命令會自動在 _posts/ 目錄下生成一個類似於上面的示例文章。

進階配置：

1. 開啟 LaTeX 支援：

mathjax: true

詳細可以看這裡

http://github.elmagnifico.tech/2021/04/30/Typora-LaTex-Mathjax/

2. 開啟 Mermaid 10.9.0 圖表支援：

mermaid: true

啟用後，您就可以在文章中使用 Mermaid 語法來繪製流程圖、序列圖、甘特圖、心智圖、時間線等各種圖表。

新版本特色：

• 自動適配深色/淺色主題
• 支援新圖表類型（心智圖、時間線等）
• 更好的效能和安全性
• 可通過 _config.yml 中的 mermaid_version 設定版本號

3. 添加更新時間：

update: 2023-12-01 10:30:00

使用 update 欄位可以記錄文章的最後更新時間。

4. 使用 CSS 漸層背景：

header-bg-css: "linear-gradient(to right, #1e3a8a, #3b82f6);"

使用 header-bg-css 欄位可以為文章頁面設定自訂的 CSS 背景樣式，支援漸層、純色或其他 CSS 背景屬性。當設定了此欄位時，會覆蓋 header-img 的背景圖片設定，讓你能夠創建更豐富的視覺效果。

常見的 CSS 背景樣式範例：

• 線性漸層："linear-gradient(45deg, #ff6b6b, #4ecdc4);"
• 徑向漸層："radial-gradient(circle, #667eea, #764ba2);"
• 純色背景："#2c3e50;"
• 多重漸層："linear-gradient(135deg, #667eea 0%, #764ba2 100%);"

5. 添加標題背景遮罩：

header-mask: 0.3

使用 header-mask 欄位可以為標題背景圖片添加半透明的黑色遮罩層，提高標題文字的可讀性。遮罩值範圍為 0.0 到 1.0：

• 0.0：完全透明（無遮罩效果）
• 0.3：30% 透明度（適合大多數情況）
• 0.5：50% 透明度（中等遮罩效果）
• 1.0：完全不透明（完全黑色遮罩）

這個功能特別適合在使用較亮的背景圖片時，確保標題文字始終保持良好的對比度和可讀性。

RSS 訂閱 & XML Sitemap

本部落格內建 RSS 訂閱和 XML Sitemap 功能，幫助讀者訂閱內容和搜尋引擎索引。

RSS 設定

在 _config.yml 中啟用 RSS 功能：

RSS: true

啟用後，RSS 訂閱源將在 /feed.xml 提供，包含：

• 最新 10 篇文章
• 完整文章內容
• 文章標籤和分類
• RSS 2.0 標準格式

Sitemap 設定

在 _config.yml 中啟用 Sitemap 功能：

sitemap: true

啟用後，XML sitemap 將在 /sitemap.xml 提供，包含：

• 網站首頁和所有靜態頁面
• 所有部落格文章
• 適當的優先度和更新頻率設定
• 符合 XML Sitemap 0.9 標準，支援 SEO 最佳實踐

多語言頁面支援：

對於具有多語言版本的頁面（如 About 頁面），sitemap 會自動生成符合 Google SEO 建議的 hreflang 標記：

# 在頁面的 Front Matter 中設定
multilingual: true

當頁面標記為 multilingual: true 時，sitemap 會自動為該頁面產生：

• 主要頁面 URL（如 /about/）
• 中文版本 URL（/about/?lang=zh）
• 英文版本 URL（/about/?lang=en）
• 預設語言標記（hreflang="x-default"）

範例輸出：

<url>
  <loc>https://blog.allenspace.de/about/</loc>
  <xhtml:link rel="alternate" hreflang="zh" href="https://blog.allenspace.de/about/?lang=zh" />
  <xhtml:link rel="alternate" hreflang="en" href="https://blog.allenspace.de/about/?lang=en" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://blog.allenspace.de/about/" />
  ...
</url>

這樣可以幫助搜尋引擎正確識別頁面的不同語言版本，為不同地區的使用者提供對應的搜尋結果。

優先度設定：

• 首頁：1.0（每週更新）
• 關於頁面：0.9（每月更新）
• 存檔頁面：0.8（每週更新）
• 其他靜態頁面：0.7（每月更新）
• 部落格文章：0.6（每年更新）

這兩個功能都使用無插件的自訂 Jekyll 模板實作，無需額外的 gem 依賴。

使用Keynote

使用方法，在markdown的Front Matter中加入：

---
layout:     keynote
iframe:     "http://huangxuan.me/js-module-7day/"
---

iframe 元素會自動調整大小以適應不同的外觀尺寸和設備方向。

由於大多數Keynote框架會阻止瀏覽器的預設滾動行為，因此設定了底部內留白來支援滾動，並提示使用者下方還有更多內容。

鳴謝

本項目基於 Hux Pro 的項目修改，同時參考了 elmagnifico 的項目。

• https://github.com/huxpro/huxpro.github.io
• https://github.com/elmagnificogi/elmagnificogi.github.io

License

Apache License 2.0.

Copyright (c) 2025-present allen5218

Allen's Blog is derived from Hux Pro (Apache License 2.0) Copyright (c) 2015-present Huxpro