hexo-theme-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hexo 主題開發

Hexo 主题开发

Hexo 基礎

Hexo 基础

開發主題前需了解的 Hexo 基礎知識。

开发主题前需了解的 Hexo 基础知识。

配置檔案

配置文件

主要配置在

_config.yml

：

yaml

undefined

主要配置在

_config.yml

：

yaml

undefined

網站設定

网站设置

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

undefined

theme: my-theme

undefined

常用指令

bash

hexo new post "標題"    # 新建文章
hexo new page "about"   # 新建頁面
hexo generate           # 產生靜態檔案
hexo server             # 啟動本地伺服器
hexo clean              # 清除快取

bash

hexo new post "标题"    # 新建文章
hexo new page "about"   # 新建页面
hexo generate           # 生成静态文件
hexo server             # 启动本地服务器
hexo clean              # 清除缓存

Front-matter

文章開頭的 YAML 區塊：

yaml

---
title: 文章標題
date: 2024-01-15
tags: [Tag1, Tag2]
categories: [Category]
---

文章开头的 YAML 区块：

yaml

---
title: 文章标题
date: 2024-01-15
tags: [Tag1, Tag2]
categories: [Category]
---

資料檔案

数据文件

在

source/_data/

放置 YAML/JSON，透過

site.data

存取：

yaml

undefined

在

source/_data/

放置 YAML/JSON，通过

site.data

存取：

yaml

undefined

source/_data/menu.yml

home: / archives: /archives


詳細基礎參考：[reference/basics.md](reference/basics.md)

home: / archives: /archives


详细基础参考：[reference/basics.md](reference/basics.md)

主題結構

主题结构

Hexo 主題遵循標準化目錄結構：

text

.
├── _config.yml    # 主題配置檔
├── languages/     # 國際化語言檔案
├── layout/        # 模板檔案
├── scripts/       # JavaScript 擴展腳本
└── source/        # 靜態資源 (CSS, JS, 圖片)

各目錄說明：

目錄/檔案	說明
`_config.yml`	主題配置，修改後自動生效無需重啟
`languages/`	存放 YAML/JSON 語言檔案
`layout/`	模板檔案，支援 EJS、Nunjucks、Pug
`scripts/`	初始化時自動載入的 JS 腳本
`source/`	靜態資源， `_` 開頭和隱藏檔案會被忽略

Hexo 主题遵循标准化目录结构：

text

.
├── _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`

模板	说明	备援
`index`	首页（必需）	-
`post`	文章页面	`index`
`page`	独立分页	`index`
`archive`	归档页面	`index`
`category`	分类归档	`archive`
`tag`	标签归档	`archive`

佈局機制

布局机制

佈局檔案需包含

body

變數以顯示模板內容：

ejs

<!-- layout.ejs -->
<!DOCTYPE html>
<html>
  <head><title><%= page.title %></title></head>
  <body><%- body %></body>
</html>

在 front-matter 指定或禁用佈局：

yaml

---
layout: false  # 禁用佈局
---

布局文件需包含

body

变量以显示模板内容：

ejs

<!-- layout.ejs -->
<!DOCTYPE html>
<html>
  <head><title><%= page.title %></title></head>
  <body><%- body %></body>
</html>

在 front-matter 指定或禁用布局：

yaml

---
layout: false  # 禁用布局
---

局部模板

使用

partial()

引入共用元件：

ejs

<%- partial('partial/header') %>
<%- partial('partial/sidebar', {active: 'home'}) %>

片段快取（用於跨頁面不變的內容）：

ejs

<%- fragment_cache('header', function(){ return '<header>...</header>'; }) %>
<%- partial('partial/header', {}, {cache: true}) %>

使用

partial()

引入共用组件：

ejs

<%- partial('partial/header') %>
<%- partial('partial/sidebar', {active: 'home'}) %>

片段缓存（用于跨页面不变的内容）：

ejs

<%- fragment_cache('header', function(){ return '<header>...</header>'; }) %>
<%- partial('partial/header', {}, {cache: true}) %>

變數系統

变量系统

全域變數

全局变量

變數	說明
`site`	網站資訊
`page`	當前頁面資訊
`config`	網站配置
`theme`	主題配置
`path`	當前頁面路徑
`url`	當前頁面完整網址

詳細變數參考：reference/variables.md

变量	说明
`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

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

設定：

yaml

language: zh-tw

在

_config.yml

设定：

yaml

language: zh-tw

或多語言

或多语言

language:

zh-tw
en

undefined

language:

zh-tw
en

undefined

語言檔案

语言文件

在

languages/

建立 YAML 檔案：

yaml

undefined

在

languages/

建立 YAML 文件：

yaml

undefined

languages/zh-tw.yml

Home: 首頁 Archive: 歸檔 Search: 搜尋

undefined

Home: 首页 Archive: 归档 Search: 搜索

undefined

模板中使用

ejs

<%= __('Home') %>
<%= _p('posts', 5) %>  <!-- 複數形式 -->

詳細說明：reference/i18n.md

ejs

<%= __('Home') %>
<%= _p('posts', 5) %>  <!-- 复数形式 -->

详细说明：reference/i18n.md

擴展 API

扩展 API

Hexo 提供強大的擴展 API，用於開發插件和自訂功能。

Hexo 提供强大的扩展 API，用于开发插件和自定义功能。

主要擴展點

主要扩展点

API	說明	用途
Filter	過濾器	修改處理中的資料
Helper	輔助函數	在模板中插入程式碼片段
Generator	產生器	根據檔案建立路由
Tag	標籤	在文章中插入自訂內容
Renderer	渲染器	轉換內容格式
Injector	注入器	在 HTML 特定位置插入程式碼
Console	控制台	建立自訂指令

API	说明	用途
Filter	过滤器	修改处理中的数据
Helper	辅助函数	在模板中插入代码片段
Generator	生成器	根据文件建立路由
Tag	标签	在文章中插入自定义内容
Renderer	渲染器	转换内容格式
Injector	注入器	在 HTML 特定位置插入代码
Console	控制台	建立自定义指令

快速範例

快速范例

javascript

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

javascript

// 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	自動化測試

类型	工具	用途
单元测试	Mocha + Chai	测试辅助函数、标签
配置验证	js-yaml	验证 YAML 格式
JS Linting	ESLint	JavaScript 品质
CSS Linting	Stylelint	样式表品质
功能测试	hexo-theme-unit-test	主题完整性
CI/CD	GitHub Actions	自动化测试

基本設置

基本设置

json

{
  "scripts": {
    "test": "mocha test/index.js",
    "lint": "eslint scripts/ source/js/"
  },
  "devDependencies": {
    "chai": "^5.0.0",
    "eslint": "^9.0.0",
    "mocha": "^10.0.0"
  }
}

json

{
  "scripts": {
    "test": "mocha test/index.js",
    "lint": "eslint scripts/ source/js/"
  },
  "devDependencies": {
    "chai": "^5.0.0",
    "eslint": "^9.0.0",
    "mocha": "^10.0.0"
  }
}

輔助函數測試範例

辅助函数测试范例

javascript

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

javascript

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

功能測試清單

功能测试清单

發布主題

发布主题

執行測試確保品質
Fork hexojs/site 儲存庫
在
```
themes.yml
```
新增主題資訊
提供 800×500px PNG 截圖

执行测试确保品质
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

基础参考：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