hexo-theme-development（Hexo 主题开发）

Hexo 主題開發

目錄

• Hexo 基礎
• 主題結構
• 模板系統
• 變數系統
• 輔助函數
• 國際化
• 擴展 API
• 測試
• 發布主題

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, 圖片)

各目錄說明：

模板系統

六種核心模板

佈局機制

佈局檔案需包含 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}) %>

變數系統

全域變數

詳細變數參考：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，用於開發插件和自訂功能。

主要擴展點

快速範例

// 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

測試

完整的主題測試包含多個層面。

測試工具

基本設置

{
  "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

發布主題

1. 執行測試確保品質
2. Fork hexojs/site 儲存庫
3. 在 themes.yml 新增主題資訊
4. 提供 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