hexo 学习 0026:hexo 主题

创建一个 Hexo 主题本质上就是构建一个特定结构的文件夹。你可以把主题想象成博客的“皮肤”和“骨架”，它决定了网站长什么样以及内容如何排列。创建过程非常简单：在 themes 目录下新建一个文件夹，然后修改博客根目录 _config.yml 中的 theme 配置项指向该文件夹名称，即可立即切换。

主题目录结构详解

一个标准的 Hexo 主题通常包含以下五个核心部分，它们各司其职，共同协作：

.
├── _config.yml      # 主题专属配置文件
├── languages        # 多语言翻译包
├── layout           # 模板文件（骨架）
├── scripts          # 自定义脚本逻辑
└── source           # 静态资源（CSS/JS/图片）

1. 配置文件 (_config.yml)

这是主题的独立配置文件。

• 功能：用于设置主题特有的选项，如菜单链接、侧边栏小工具、颜色方案等。
• 特性：与博客根目录的 _config.yml 不同，修改主题配置文件后无需重启 Hexo Server。Hexo 会实时监测并自动加载更改，这对于调试主题非常方便。

2. 布局文件夹 (layout)

这是主题的核心，决定了网页的结构和内容呈现方式。

• 功能：存放模板文件。Hexo 会根据文件扩展名自动选择对应的模板引擎。
• 引擎支持：Hexo 内置 Nunjucks 引擎。如果你习惯使用 EJS 或 Pug，需要安装相应的插件。
• 文件命名规则：
  • layout.ejs：使用 EJS 引擎渲染。
  • layout.njk：使用 Nunjucks 引擎渲染。
• 比喻：如果把博客内容比作“水”，那么 layout 文件夹里的模板就是“杯子”。水倒进什么形状的杯子，最终就呈现什么形状。

3. 脚本文件夹 (scripts)

• 功能：存放 JavaScript 文件。
• 机制：在 Hexo 启动时，此文件夹内的所有 JS 文件会被自动加载和执行。
• 用途：用于扩展 Hexo 的功能，例如注册新的标签插件（Tag Plugins）、过滤器（Filters）或生成器（Generators）。这相当于给博客安装了“微型插件”。

4. 源文件文件夹 (source)

• 功能：存放静态素材，如 CSS 样式表、JavaScript 库、字体文件或图片。
• 处理逻辑：
  • 可渲染文件：Hexo 会处理这些文件（如编译 Sass），然后保存到 public 文件夹。
  • 不可渲染文件：直接原样复制到 public 文件夹。
• 忽略规则：文件名或文件夹名以 _（下划线）开头，或者是隐藏文件（以 . 开头），都会被 Hexo 忽略，不会发布到最终网站。这让你可以在主题源码中保留备注文件或草稿而不影响输出。

5. 语言文件夹 (languages)

• 功能：存放国际化（i18n）翻译文件。
• 作用：允许你的主题支持多种语言。当用户切换网站语言时，主题会自动读取此处对应的翻译文本，显示菜单、按钮等的本地化内容。

命令与工作流示例

在开发主题时，你不需要频繁重启服务器，但需要确保文件被正确监听。

启动开发服务器：

hexo server

操作说明：

1. 修改 themes/你的主题/_config.yml：保存后，浏览器自动刷新，配置立即生效。
2. 修改 layout 或 source 文件：Hexo 检测到变动，重新编译并刷新页面。
3. 修改 scripts 文件：由于脚本是在启动时加载的，修改 JS 文件通常需要重启服务器 (Ctrl+C 停止，再运行 hexo server) 才能生效。

概念辨析：根目录配置 vs 主题配置

很多初学者容易混淆博客根目录的 _config.yml 和主题文件夹内的 _config.yml。

特性	根目录 _config.yml	主题目录 _config.yml
位置	blog_root/_config.yml	blog_root/themes/主题名/_config.yml
作用范围	全局配置（站点标题、URL、部署设置、启用哪个主题）	局部配置（主题特有的颜色、菜单、小工具开关）
生效机制	修改后通常需重启服务器	修改后自动更新，无需重启
优先级	其中的 theme 字段决定加载哪个主题配置	被根目录配置选中的主题，其配置才生效

比喻：根目录配置是“房东”，决定把房子租给哪个租客（主题）；主题配置是“租客”自己的内部装修规则。房东换了租客，内部的装修风格就全变了。

发布主题到官方列表

当你完成主题开发并希望分享给社区时，可以将其发布到 Hexo 主题列表。这需要向 hexojs/site 仓库提交合并申请（Pull Request）。

步骤 1：复刻仓库
首先将官方站点仓库克隆到本地，并安装依赖。

git clone https://github.com/<你的用户名>/site.git
cd site
npm install

注意：这里通常需要先 Fork 官方的 hexojs/site 到你自己的 GitHub 账号，然后克隆你自己的这个 Fork 仓库。

步骤 2：创建主题描述文件
在 source/_data/themes/ 目录下，创建一个以你的主题名称命名的 YAML 文件。

配置示例 (source/_data/themes/我的主题.yml)：

description: A brand new default theme for Hexo.
link: https://github.com/你的用户名/你的主题仓库地址
preview: http://你的演示站点地址
tags:
  - official
  - responsive
  - widget
  - two_column
  - one_column

参数说明：

• description：主题的简短介绍。
• link：主题源代码的 GitHub 仓库链接。
• preview：主题在线演示站点的网址。
• tags：标签列表，用于分类检索（如是否响应式、单栏/双栏等）。

步骤 3：添加截图
在 source/themes/screenshots 文件夹中放入主题的截图。

• 命名要求：文件名必须与主题名称完全一致。
• 格式要求：必须是 PNG 格式。
• 尺寸要求：严格为 800x500 像素。

步骤 4：提交更改
将修改推送到你的远程仓库，并在 GitHub 上向 hexojs/site 发起 Pull Request。

git add .
git commit -m "Add new theme: 你的主题名"
git push origin master

随后在 GitHub 网页界面点击 “New Pull Request”，详细描述你的主题特点和改动，等待官方审核合并。

注意事项

1. 脚本重载：再次强调，修改 scripts 文件夹内的代码后，必须重启 hexo server，因为脚本仅在进程启动时加载一次。
2. 文件忽略：在 source 文件夹中调试时，如果不想让某些临时文件被发布，记得在文件名前加 _。
3. 截图规范：发布主题时，截图尺寸不符会导致预览图变形或被拒绝，请务必使用图像处理工具裁剪为 800x500。
4. 模板引擎：如果你的主题使用了 EJS 或 Pug，记得在文档中提醒用户安装对应的插件（如 hexo-renderer-ejs 通常是内置的，但 Pug 可能需要额外安装），否则用户使用时会报错。