陌讯skills聚合平台

hexo-theme-development

📁 hsiangfeng/hexo-skills 📅 Today
0
总安装量
1
周安装量
安装命令
npx skills add https://github.com/hsiangfeng/hexo-skills --skill hexo-theme-development

Agent 安装分布

amp 1
opencode 1
kimi-cli 1
codex 1
github-copilot 1
antigravity 1

Skill 文档

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

發布主題

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

參考資料

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。