ParticleXF

ParticleX 的 Hexo 主题分支，基于上游主题做了更偏个人博客的定制：双主题、星空背景、响应式 TOC、代码折叠/换行、数学公式、Mermaid、归档筛选和多种评论方案等。

特性

• 柔和深色 / 暖浅色双主题，使用 CSS 变量切换
• 顶栏主题切换并记忆用户选择
• 动态星空背景，浅色模式下显示更轻量的背景效果
• 文章 TOC：滚动高亮、平滑跳转、窄屏浮层
• 代码块：Highlight.js 高亮、行号、复制、自动换行、长代码折叠
• 数学公式、Mermaid 图表、图片预览、文章加密、归档标题筛选
• 通过 Front Matter 设置文章置顶权重和首页摘要
• 支持 giscus、Gitalk、Waline、Twikoo
• {% note %} 提示框标签

安装

方式一：直接克隆到主题目录

cd your-hexo-site
git clone https://github.com/FloranceYeh/hexo-theme-particlexf themes/particlexf

然后在站点根目录的 _config.yml 中启用主题：

theme: particlexf

方式二：作为子模块（推荐）

cd your-hexo-site
git submodule add https://github.com/FloranceYeh/hexo-theme-particlexf themes/particlexf

也记得在 _config.yml 中启用主题。

建议的站点依赖

npm install hexo-server hexo-deployer-git

Mermaid、加密和评论客户端由主题从 CDN 加载，不需要额外安装前端包；评论系统仍需各自的仓库凭据或服务端部署。

Hexo 兼容设置

为了避免 Hexo 自带能力和主题功能冲突，建议顺手检查下面几项：

关闭自带代码高亮

如果你在使用主题自带的 Highlight.js，建议关闭 Hexo 自带高亮。

把 _config.yml 中的 syntax_highlighter 配置改为空值即可。

syntax_highlighter:

禁用自动归档页

如果你不需要 Hexo 自动生成年度 / 月度 / 日度归档，建议关闭它们，避免和主题的归档页体验重复。

archive_generator:
  enabled: true
  per_page: 0
  yearly: false
  monthly: false
  daily: false

修改后建议执行一次 hexo clean。

主题配置

主题默认配置位于 _config.yml。直接克隆主题时可以修改该文件，但更推荐在站点根目录使用 _config.particlexf.yml 覆盖配置，这样更新主题或使用 Git 子模块时不会混入个人配置。修改配置后请执行一次 hexo clean。

常用项如下：

avatar: /images/avatar.jpg

background:
  - /images/background.jpg

loading: /images/loading.gif

menu:
  Home:
    name: house
    theme: solid
    link: /
  About:
    name: id-card
    theme: solid
    link: /about

card:
  enable: true
  description: |
    Your name here.
    Your blog subtitle.

highlight:
  enable: true
  wrap: true
  collapse:
    enable: true
    lines: 20

math:
  enable: true

mermaid:
  enable: true

preview:
  enable: true

search:
  enable: true

stellars:
  enable: true
  seedChanger:
    enable: false

配置项索引

当前模板固定使用 Atom One Dark Reasonable / Atom One Light 两套 Highlight.js 样式，Mermaid 固定使用 forest 主题。默认配置中遗留的 highlight.style 和 mermaid.options 目前不会改变这些值。

文章 Front Matter

除了 Hexo 标准的 title、date、tags、categories 外，ParticleXF 会直接读取以下字段：

---
title: 示例文章
date: 2026-07-26 12:00:00
tags:
  - hexo
categories:
  - Tutorial
description: |
  首页显示的摘要，支持 **Markdown**。
pinned: 10
toc: true
comments: true
# secret: "change-me"
---

浏览器端加密只能作为访问门槛，不能视为强安全保护；标题、元数据和 TOC 标题仍然公开。加密文章还应单独设置 description，或在受保护内容前放置 <!-- more -->，否则首页摘要回退可能直接暴露正文。

特殊页面

分类页与标签页

分别创建带有 type 的索引页：

# source/categories/index.md
---
title: 分类
type: categories
---

# source/tags/index.md
---
title: 标签
type: tags
---

/archives/ 归档页由 Hexo 的归档生成器创建。启用 search.enable 后，搜索框只按标准化后的文章标题即时筛选。

友链页

主题会为 /links/ 路由选择专用友链布局。创建 source/links/index.md，并在 source/_data/links.yml 中按分组维护数据：

朋友们:
  Example:
    name: 示例博客
    url: https://example.com
    ava: https://example.com/avatar.png
    des: 一段简短介绍

source/links/index.md 中的 Markdown 会显示在友链卡片之后。在该页面的 Front Matter 中加入 comments: true 可显示已配置的评论系统。

功能行为

文章目录

宽屏下 TOC 是文章右侧的粘性侧栏；宽度不超过 1200px 时变为右下角浮层，通过悬浮目录按钮打开。它会跟踪当前标题、自动滚动活动目录项、平滑跳转，并提供“顶部”和“评论/底部”快捷入口。点击外部、再次点击目录按钮、选择目录项或按 Escape 都会关闭浮层。

代码块

启用 highlight.enable 后，每个 pre 代码块都会获得语言高亮、行号和复制按钮。highlight.wrap 控制软换行；highlight.collapse.enable 开启时，超过 highlight.collapse.lines 行的代码默认折叠，并显示展开/收起控件。

数学公式与 Mermaid

KaTeX 支持 $...$、$$...$$、\(...\) 和 \[...\]。在当前 Markdown 渲染流程中，Mermaid 使用原始 HTML 最稳定：

<div class="mermaid">
graph TD
  A --> B
</div>

首页与视觉交互

• 点击全屏首页首屏的中央区域，会平滑滚动一个视口高度到文章列表。
• 主题默认使用深色模式，选择会以 theme 为键存入 localStorage，同时联动代码高亮和星空配色。
• 桌面个人卡片内容超过视口高度的 80% 时，会变成独立滚动区域。
• 原生 <details> / <summary> 内容带有主题样式。
• 图片预览作用于页面中的全部图片；点击遮罩或调整窗口大小会关闭预览。

评论配置

主题内置四种评论适配。配置并开启其中一种后，还要在需要评论的文章或友链页设置 comments: true。同时开启多个适配器会全部渲染，因此建议一次只使用一种。

giscus:
  enable: false

gitalk:
  enable: false

waline:
  enable: false
  serverURL: https://your-waline-server.example

twikoo:
  enable: false

• giscus 需要 repo、repoID、category、categoryID，其余 data 属性由同名配置传入。
• Gitalk 需要 GitHub OAuth 凭据、仓库、所有者和管理员列表；多个管理员用逗号分隔。
• Waline 至少需要 serverURL，主题还会传入表情、语言、用户信息字段、登录方式、分页等客户端选项。
• Twikoo 需要 envID，并支持 region、path、lang。

只有当前页面设置了 comments: true 且至少启用一个评论适配器时，TOC 底部快捷入口才会指向评论区；否则会指向页脚。

Note 标签

{% note tip %}
提示内容，支持 **Markdown**。
{% endnote %}

{% note warning 注意 %}
自定义标题。
{% endnote %}

{% note danger no-icon %}
不显示图标。
{% endnote %}

支持的类型包括：note、info、tip、success、warning、danger、quote。

目录结构

hexo-theme-particlexf/
├── _config.yml
├── layout/
├── scripts/
├── source/
│   ├── css/main.css
│   └── js/
└── package.json

开发

在博客站点目录中执行：

hexo clean && hexo server

修改主题文件后刷新页面即可；修改配置后建议先清理缓存再重新生成。

许可证

MIT。

致谢

• hexo-theme-particlex
• Font Awesome
• Highlight.js
• Waline