XFM Theme

高端大气的 Hexo 主题，一套代码覆盖博客 / 笔记 / 文档三种形态。

XFM 是一套面向长期写作的 Hexo 主题：全套设计令牌驱动、深浅色对称、三模式切换、几乎所有形态都由配置决定，无需改模板。

特性总览

维度	能力
形态	blog 卡片流 / notes 笔记树 / docs 三栏文档
外观	深浅色三态切换（浅色、深色、跟随系统）、主色自定义、圆角档位、磨砂导航、背景光晕
导航	两级下拉菜单、移动端抽屉、当前项高亮、滚动自动隐藏、RSS 入口
搜索	内置全文检索索引 + Cmd/Ctrl+K 唤起 + 键盘导航 + 关键词高亮
目录	侧栏目录件 / 独立目录栏，滚动跟随高亮、自动滚入可见区
代码块	语言标签、Mac 风格三色点、复制按钮、长代码折叠、gutter 行号、自研深浅色配色
标签插件	提示块、折叠、选项卡、时间轴、栅格、按钮、徽标、图标、流程图、链接卡片
内容增强	标题锚点、表格滚动容器、外链新窗、图片懒加载与灯箱、任务列表、数学公式、Mermaid
多语言	内置 zh-CN / en，界面文案抽离到 `languages/`；导航栏翻译图标一键前后端切换，选择本地记忆
广告变现	Google AdSense（自动广告 + 6 个手动广告位、延迟加载、广告标识、路径排除、单篇关闭、`data-adtest` 预览）
评论	giscus / utterances / waline / twikoo / disqus / disqusjs / valine / 畅言
SEO	OG / Twitter Card、canonical、JSON-LD、内置 sitemap.xml 与 robots.txt、404 页
阅读体验	阅读进度条、平滑滚动、滚动入场动画、文章过时提醒、版权卡、打赏、分享、相关文章
悬浮按钮	右下角按钮组：文档目录（按模式显示，其余模式不渲染）+ 回到顶部（滚动淡入），窄屏出现、桌面隐藏
交付质量	自适应三档（mobile / tablet / desktop，可配置）、触摸与刘海屏适配、打印样式、动效降级（`prefers-reduced-motion`）、语义化标签

二、安装

# npm（推荐，便于版本升级）
npm i hexo-theme-xfm

# 或 git clone（跟随仓库最新提交）
git clone https://github.com/xfm0797/hexo-theme-xfm.git themes/xfm

安装后把主题放到站点的 themes/xfm 目录（npm 安装的从 node_modules/hexo-theme-xfm 复制或软链），站点 _config.yml：

theme: xfm

依赖

Hexo 8 起核心不再内置渲染器与部分生成器，请在站点安装（通常 hexo init 已自带）：

npm i hexo-renderer-marked hexo-renderer-ejs \
      hexo-generator-index hexo-generator-archive \
      hexo-generator-category hexo-generator-tag

按需增强（可选）：

功能	依赖
RSS	`npm i hexo-generator-feed`
KaTeX / MathJax	无需安装，主题按配置从 CDN 加载
Mermaid	无需安装，主题按配置从 CDN 加载

站点根目录的 package.json 需要包含 "hexo": { "version": "..." } 字段，Hexo 才会加载外部插件（这也是 404 / sitemap 等内置生成器能否工作的前提）。

三、三种模式

在主题 _config.yml 顶部切换：

mode: blog    # blog / notes / docs

blog：首页 Hero + 文章卡片流 + 右侧挂件栏，适合个人博客
notes：左侧笔记树（按分类/日期分组）+ 沉浸式窄栏阅读 + 右侧目录
docs：左侧文档树 + 正文 + 右侧目录三栏，适合产品文档

单篇文章可通过 front-matter 覆盖：mode: docs。

文档模式侧边栏

在站点 source/_data/docs.yml 中定义树形结构（字段名可通过 docs.data_file 改）：

- title: 快速开始
  children:
    - title: 主题简介
      path: /docs/intro/
    - title: 安装部署
      path: /docs/install/

未定义该文件时，会自动按页面的 order + title 生成侧边栏。

目录树的默认展开范围由两个开关决定，收起 / 展开是纯 CSS（无 JS 时保持默认展开，不会先闪开再收起）：

docs:
  expanded: true      # true 全部展开；false 只展开当前页所在分支
  auto_expand: true   # 是否自动展开当前页所在分支

带子节点的条目本身就是折叠开关：点箭头、或点分组文本都能展开 / 收起；按钮带 aria-expanded，可 Tab 聚焦后用回车 / 空格操作。

笔记模式侧边栏

notes:
  note_categories: []   # 只收录这些分类的文章，留空 = 不过滤
  note_tags: []         # 只收录带这些标签的文章，留空 = 不过滤；与上一项同时配置时取交集
  group_by: category    # category / date / none（none = 平铺列表，不出现分组头）
  sort_by: date         # title / date / order
  order: desc           # asc / desc
  collapsed: false      # 分组默认是否折叠（当前页所在分组始终展开）
  show_date: true

想让某篇文章在左侧导航里常驻（点进正文后导航不消失），在它的 front-matter 写 mode: notes。

项目仓库： https://github.com/xfm0797/hexo-theme-xfm

项目演示：https://doc.lovou.pw

开发了套hexo-theme-xfm主题，兼具三种形态模式（blog/note/docs），有需要的朋友可以下载使用