Hexo 主題開發
目錄
Hexo 基礎
開發主題前需了解的 Hexo 基礎知識。
配置檔案
主要配置在 _config.yml：
# 網站設定
title: My Blog
author: Author Name
language: zh-tw
# URL 設定
url: https://example.com
permalink: :year/:month/:day/:title/
# 目錄設定
source_dir: source
public_dir: public
# 主題設定
theme: my-theme常用指令
hexo new post "標題" # 新建文章
hexo new page "about" # 新建頁面
hexo generate # 產生靜態檔案
hexo server # 啟動本地伺服器
hexo clean # 清除快取Front-matter
文章開頭的 YAML 區塊：
---
title: 文章標題
date: 2024-01-15
tags: [Tag1, Tag2]
categories: [Category]
---資料檔案
在 source/_data/ 放置 YAML/JSON，透過 site.data 存取：
# source/_data/menu.yml
home: /
archives: /archives詳細基礎參考：reference/basics.md
主題結構
Hexo 主題遵循標準化目錄結構：
.
├── _config.yml # 主題配置檔
├── languages/ # 國際化語言檔案
├── layout/ # 模板檔案
├── scripts/ # JavaScript 擴展腳本
└── source/ # 靜態資源 (CSS, JS, 圖片)各目錄說明：
| 目錄/檔案 | 說明 |
|---|---|
_config.yml | 主題配置，修改後自動生效無需重啟 |
languages/ | 存放 YAML/JSON 語言檔案 |
layout/ | 模板檔案，支援 EJS、Nunjucks、Pug |
scripts/ | 初始化時自動載入的 JS 腳本 |
source/ | 靜態資源，_ 開頭和隱藏檔案會被忽略 |
模板系統
六種核心模板
| 模板 | 說明 | 備援 |
|---|---|---|
index | 首頁（必需） | - |
post | 文章頁面 | index |
page | 獨立分頁 | index |
archive | 歸檔頁面 | index |
category | 分類歸檔 | archive |
tag | 標籤歸檔 | archive |
佈局機制
佈局檔案需包含 body 變數以顯示模板內容：
<!-- layout.ejs -->
<!DOCTYPE html>
<html>
<head><title><%= page.title %></title></head>
<body><%- body %></body>
</html>在 front-matter 指定或禁用佈局：
---
layout: false # 禁用佈局
---局部模板
使用 partial() 引入共用元件：
<%- partial('partial/header') %>
<%- partial('partial/sidebar', {active: 'home'}) %>片段快取（用於跨頁面不變的內容）：
<%- fragment_cache('header', function(){ return '<header>...</header>'; }) %>
<%- partial('partial/header', {}, {cache: true}) %>變數系統
全域變數
| 變數 | 說明 |
|---|---|
site | 網站資訊 |
page | 當前頁面資訊 |
config | 網站配置 |
theme | 主題配置 |
path | 當前頁面路徑 |
url | 當前頁面完整網址 |
詳細變數參考：reference/variables.md
輔助函數
Hexo 提供豐富的內建輔助函數：
- URL 類：
url_for(),relative_url(),full_url_for() - HTML 標籤類：
css(),js(),link_to(),image_tag() - 條件判斷類：
is_home(),is_post(),is_archive() - 字串處理類：
trim(),strip_html(),truncate() - 日期時間類：
date(),time(),relative_date() - 列表類：
list_categories(),list_tags(),paginator()
詳細函數參考：reference/helpers.md
國際化
配置語言
在 _config.yml 設定：
language: zh-tw
# 或多語言
language:
- zh-tw
- en語言檔案
在 languages/ 建立 YAML 檔案：
# languages/zh-tw.yml
Home: 首頁
Archive: 歸檔
Search: 搜尋模板中使用
<%= __('Home') %>
<%= _p('posts', 5) %> <!-- 複數形式 -->詳細說明：reference/i18n.md
擴展 API
Hexo 提供強大的擴展 API，用於開發插件和自訂功能。
主要擴展點
| API | 說明 | 用途 |
|---|---|---|
| Filter | 過濾器 | 修改處理中的資料 |
| Helper | 輔助函數 | 在模板中插入程式碼片段 |
| Generator | 產生器 | 根據檔案建立路由 |
| Tag | 標籤 | 在文章中插入自訂內容 |
| Renderer | 渲染器 | 轉換內容格式 |
| Injector | 注入器 | 在 HTML 特定位置插入程式碼 |
| Console | 控制台 | 建立自訂指令 |
快速範例
// scripts/my-plugin.js
// 自訂輔助函數
hexo.extend.helper.register('greeting', function(name) {
return `Hello, ${name}!`;
});
// 文章渲染後處理
hexo.extend.filter.register('after_post_render', function(data) {
// 修改文章內容
return data;
});
// 自訂標籤
hexo.extend.tag.register('note', function(args, content) {
return `<div class="note">${content}</div>`;
}, { ends: true });詳細 API 參考：reference/api.md
測試
完整的主題測試包含多個層面。
測試工具
| 類型 | 工具 | 用途 |
|---|---|---|
| 單元測試 | Mocha + Chai | 測試輔助函數、標籤 |
| 配置驗證 | js-yaml | 驗證 YAML 格式 |
| JS Linting | ESLint | JavaScript 品質 |
| CSS Linting | Stylelint | 樣式表品質 |
| 功能測試 | hexo-theme-unit-test | 主題完整性 |
| CI/CD | GitHub Actions | 自動化測試 |
基本設置
{
"scripts": {
"test": "mocha test/index.js",
"lint": "eslint scripts/ source/js/"
},
"devDependencies": {
"chai": "^5.0.0",
"eslint": "^9.0.0",
"mocha": "^10.0.0"
}
}輔助函數測試範例
// test/helpers/my-helper.js
const Hexo = require('hexo');
describe('my-helper', () => {
const hexo = new Hexo(__dirname, { silent: true });
before(() => hexo.init());
const helper = hexo.extend.helper.get('my_helper').bind(hexo);
it('should return formatted text', () => {
helper('hello').should.equal('<span>hello</span>');
});
});功能測試清單
- DOCTYPE 和 charset 正確
- 首頁文章列表和分頁
- 文章頁標題、內容、標籤
- 歸檔頁按時間排序
- 響應式設計正常
詳細測試參考：reference/testing.md
發布主題
- 執行測試確保品質
- Fork hexojs/site 儲存庫
- 在
themes.yml新增主題資訊 - 提供 800×500px PNG 截圖
參考資料
- 基礎參考：reference/basics.md
- 模板參考：reference/templates.md
- 變數參考：reference/variables.md
- 輔助函數參考：reference/helpers.md
- 國際化參考：reference/i18n.md
- API 參考：reference/api.md
- 測試參考：reference/testing.md
- 基本範例：examples/basic-theme.md
- 進階用法：examples/advanced-usage.md