Yin-Hongwei Hexo 主题制作

Hexo 主题制作

用过默认主题，也试过别人写的主题，最后还是想有一套自己的。于是做了 Yin 主题。本文记录从零搭建 Hexo 主题的完整流程：目录结构 → 数据来源 → 各页面实现 → 发布到官方主题库。

一、前置知识

制作 Hexo 主题前，建议先了解以下三块：

类别 技术选型 作用
模板引擎 Pug 通过 extends / include / mixin 复用页面结构
CSS 预处理 Stylus 变量、嵌套、模块化样式管理
Hexo 文档 官方文档 配置项、变量、辅助函数

核心思路：layout 写结构，source 写样式，相同部分抽成模块，各页面按需组合。

二、项目创建

可以用脚手架生成，也可以手动创建。手动方式如下：

1、创建主题目录

在站点根目录的 themes/ 下新建文件夹（如 hexo-theme-Yin），并在站点根目录的 _config.yml 中切换主题：

theme: hexo-theme-Yin  # 替换默认的 landscape

2、最小目录结构

themes/hexo-theme-Yin/
├── _config.yml   # 主题配置（菜单、评论、打赏等）
├── layout/       # 页面模板
└── source/       # 静态资源（CSS、JS、字体等）

需要实现的页面通常包括：首页、文章详情、归档、标签、关于。这些页面共享头部、底部和 <head> 内容，应拆成独立模块，避免重复编写。

3、搭建基础布局

在 layout/ 下创建 index.pug（首页），在 layout/includes/ 下创建 layout.pug（全局布局）。layout.pug 只负责骨架，具体模块交给子文件处理：

首页继承全局布局：

extends includes/layout.pug

本地预览：

hexo s
# 访问 http://localhost:4000/

样式写在 source/ 目录下，Stylus 的变量和嵌套能很好地管理全局样式。

三、页面数据来源

模板渲染时，数据来自三个配置文件和 Hexo 内置对象。

1、站点配置（根目录 _config.yml）

控制整站行为，常用字段：

字段 说明
title / subtitle 站点标题与副标题
url 站点地址，影响 url_for() 生成路径
permalink 文章 URL 规则
theme 当前使用的主题名

2、Hexo 内置对象

Hexo 在渲染时注入 变量 和 辅助函数。

常用变量：

变量 作用域 说明
site 全局 全站文章、页面、分类、标签集合
page 当前页 当前页的文章列表或单页信息
post 文章页 单篇文章详情，含 tags、categories、published
theme 全局 主题 _config.yml 中的配置项

site 对象结构示意：

site = {
  posts: [],       // 文章对象数组
  pages: [],       // 页面对象数组
  categories: [],  // 分类对象数组
  tags: []         // 标签对象数组
}

常用辅助函数：

类别 函数 用途
页面判断 is_home()、is_post()、is_tag()、is_category()、is_archive() 判断当前页面类型
时间处理 date()、time() 格式化日期时间
列表生成 list_categories()、list_tags()、tagcloud() 生成分类/标签列表和标签云
文章目录 toc() 根据标题生成目录
分页 paginator() 生成分页导航

3、主题配置（themes/<theme>/_config.yml）

存放主题专属选项，通过 theme.xxx 在模板中读取。典型配置：

menu:
  Home: /
  Archives: /archives
  Tags: /tags
  About: /about

reward:
  enable: true
  wechat: /img/weixin.jpg

四、各页面实现

layout.pug 是各页面的公共骨架，内部再拆分为 head、header、footer 等子模块。

1、全局布局（layout.pug）

头部（header.pug）

利用 url_for() 将相对路径转为绝对路径，theme.menu 读取主题配置中的导航菜单：

header#header
  nav#navbar
    span.nav-left
      div.tou-img
        img(src="/img/tou.jpg")
      a#site-name(href=url_for('/'))= config.title
    i.fa.fa-bars.toggle-menu.nav-right(aria-hidden="true")
    span.nav-right.menus
      each url, label in theme.menu
        a.site-page(href=url)= label

内容区

中间内容因页面而异，在 layout.pug 中预留 block content，由子模板填充。

尾部（footer.pug）

放置版权、备案等声明信息。

2、首页（index.pug）

extends includes/layout.pug

block content
  include includes/recent-posts.pug
  include includes/partial/pagination.pug

首页主要做两件事：文章列表和分页。文章数据来自 page 变量，分页用 paginator() 辅助函数：

-
  var options = {
    prev_text: '<i class="fa fa-chevron-left"></i>',
    next_text: '<i class="fa fa-chevron-right"></i>',
    mid_size: 1
  }
nav#pagination
  if !is_post()
    .pagination
      != paginator(options)

3、文章详情页（post.pug）

详情页侧重阅读体验，可扩展打赏、上下篇导航和评论等功能。

微信打赏

在主题 _config.yml 中配置：

reward:
  enable: true
  wechat: /img/weixin.jpg

在 post.pug 中引用：

if theme.reward.enable
  .qr-code
    img.qrcode-img(src=theme.reward.wechat)
    .qrcode-desc 微信打赏

上下篇导航

与首页分页不同，详情页只需上一篇 / 下一篇链接，可在分页模块中做兼容：

if page.prev
  .prev-post.pull-left
    a(href=url_for(page.prev.path))
      i.fa.fa-chevron-left
      span= page.prev.title
if page.next
  .next-post.pull-right
    a(href=url_for(page.next.path))
      span= page.next.title
      i.fa.fa-chevron-right

评论

借助第三方服务，在主题 _config.yml 中配置后在 comments/ 目录引用即可。常见方案：

Gitalk（gitalk.github.io）

gitalk:
  enable: true
  id: ''
  owner: your-github-username
  admin: your-github-username
  repo: your-repo-name
  client_id: ''
  client_secret: ''

Disqus（disqus.com）

disqus:
  enable: false
  shortname: your-shortname
  count: true

4、关于页

在站点 source/about/ 下创建 index.md，写入内容后 Hexo 自动生成页面，再用主题样式调整排版即可。

5、归档页

按年份分组展示文章时间线，用 Pug mixin 实现：

mixin articleSort(posts)
  .article-sort
    - var year
    - posts.each(function (article) {
      - var tempYear = date(article.date, 'YYYY')
      if tempYear !== year
        - year = tempYear
        .article-item.year= year
      .article-item
        time.article-item__time= date(article.date)
        a.article-item__title(href=url_for(article.path))= article.title || 'No Title'
    - })

6、标签页

利用 list_tags() 生成标签云，在模板中按 page.type 判断渲染：

if page.type === 'tags'
  article#tag
    h1.tag-title 标签
    hr
    .tag-cloud-tags!= list_tags()

五、发布到官方主题库

主题完成后，可向 hexojs/site 提交，收录到 Hexo 官方主题列表。

  1. Fork hexojs/site 仓库
  2. 编辑 source/_data/theme.yml，添加主题信息：
- name: Yin
  description: A simple & beautiful & fast theme for Hexo
  link: https://github.com/Yin-Hongwei/hexo-theme-Yin
  preview: https://yin-hongwei.github.io/
  tags:
    - simple
    - beautiful
    - fast
  1. 在 source/theme/screenshots/ 放置 800×500 的预览图，文件名与主题名一致
  2. 提交到自己 fork 的仓库，向官方仓库发起 Pull Request

审核合并后，主题就会出现在官方主题列表中。

微信打赏