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>');
  });
});

功能測試清單

詳細測試參考：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

hexo-theme-development