一、文档树：默认收起 + 点击展开

根因（主题的三个缺口）

主题对 docs 侧栏只输出 .xfm-nav-item.has-children + .xfm-nav-toggle + 空 <i class="xfm-arrow">，但：

1. CSS 只实现了 .xfm-nav-group（笔记侧栏）的折叠，.xfm-sidebar-nav 下没有任何收起规则 → 整棵树永远全展开；
2. core.js 只给 .xfm-nav-group-head 绑了点击，.xfm-nav-toggle 无任何事件 → 点箭头毫无反应；
3. .xfm-arrow 全主题没有样式 → 连箭头都看不见。

站点层修复

两者经 theme_config.custom.css / custom.js 引入。

二、xongyi 文档按 xfm 结构重写（8 篇 → 21 篇）

原先 xongyi 只有 8 篇扁平文档。这次重写为与 xfm 同构的分组树：

内容取自主题权威源：README.md、_config.yml、examples/config.*.yml、scripts/icons.js（52 个图标）、languages/、layout/ 与 style.css 的 CSS 令牌。front-matter 与 xfm 对齐，_data/docs.yml 的 xongyi 分组改为同构三级树。

校验

• 构建 91 files，0 error；文档页未渲染的标签残留 0。
• 侧栏 49 条链接全部命中，50 个文档页无孤儿，70 个 HTML 中 /docs/ 链接 0 失效。
• jsdom 模拟点击：收起分组 aria-expanded=false → 点标签展开 → 点箭头收起 → preventDefault 正确；叶子链接不被拦截。

站点构成

整站由 hexo-theme-xfm 的 docs 模式驱动，使用 Hexo 8 构建；主题通过 git submodule 引用官方仓库 themes/xfm，仓库内不存放主题源码。

文档侧栏树

侧栏树由 source/_data/docs.yml 定义，按主题分区、可递归到三级，并支持点击展开 / 收起、默认折叠：

1
2
3
4
5
6

- title: hexo-theme-xfm
  children:
    - title: 快速开始
      children:
        - title: 主题简介
          path: docs/xfm/intro

文档页统一采用「目录 + index.md」的组织方式，以产出 pretty URL。

站点级补丁

主题以 submodule 引入，所有定制都通过站点层实现，主题升级不冲突：

• source/css/xfm-docs-tree.css + source/js/xfm-docs-tree.js：文档树分组折叠
• source/js/xfm-tabs.js：选项卡切换
• scripts/pagination-view.js：统一分页结构

本地构建

1
2
3

git clone --recursive https://github.com/xfm0797/xfm-docs.git
cd xfm-docs && npm install
hexo clean && hexo generate

你要主题还是要整站

• 只想把主题装进自己的 Hexo 站点 → 前往主题仓库
• 想要「主题 + 站点」的完整用法参考 → 直接用本仓库

一键部署

仓库内已内置全部构建配置，Fork 或导入后选择任一平台即可部署：

主题以 git submodule 引入，部署时需启用 Recursive / Submodules 克隆选项。

免配置的地址处理

_config.yml 里的 url / root 是占位值，无需手工修改：GitHub Pages 工作流会在构建前读取真实地址并生成覆盖配置，Fork 到自己账号或绑定自定义域名都能自动生效。

目标结构

1
2
3

首页 · 归档 · 分类 · 标签 · 文档 · 笔记 · 更多 ▾
                                          ├─ 友链
                                          └─ 关于

「更多」在主题里本就支持 children 下拉，直接复用。

新增笔记入口

「笔记」指向 /notes/，新建 source/notes/index.md 并设置 mode: notes，左侧会渲染按分类归集的笔记树。

一个坑：Hexo 合并配置时的键顺序

主题自带一份默认菜单（含「更多」），站点 theme_config.menu 会与之合并。问题在于 Hexo 用的是 deepMerge(theme.config, theme_config)，底层保留主题已有的键序，站点新增的键一律追加到末尾 —— 于是「文档 / 笔记」被排到了「更多」之后，顺序错乱。

1
2

// before_generate 时把 theme.menu 的键重排为期望顺序，
// 未列出的键按原序追加，便于日后扩展。

校验

• 导航顺序正确：首页 → 归档 → 分类 → 标签 → 文档 → 笔记 → 更多，下拉内为友链 / 关于。
• /notes/ 渲染 data-mode="notes"，笔记侧栏按分类分组。
• 八个导航目标（/、/archives/、/categories/、/tags/、/docs/、/notes/、/links/、/about/）全部返回 200。
• 构建 73 files，0 error。

关键机制：单页 front-matter 覆盖主题形态

主题 layout.ejs 的形态解析顺序是：

1

page.mode  ||  theme.mode  ||  'blog'

也就是说 单页 front-matter 的 mode 会覆盖主题默认模式。所以「站点默认 blog + 文档页 docs」可以在同一站共存：

据此把 theme_config.mode 由 docs 改为 blog。

导入官方 xfm 文档集

从外部导入了一套官方 xfm 文档（28 篇，扁平结构 /docs/<slug>/），处理方式：

• 替换：移除此前手写的 source/docs/xfm/（8 篇），改用导入集。
• 保留：source/docs/xongyi/（8 篇）原样保留。
• 侧栏：source/_data/docs.yml 采用导入版的 8 个分组，并在末尾追加「hexo-theme-xongyi」分组，共 9 组 / 35 条链接。

source/docs/ 合计 36 篇（28 xfm + 8 xongyi）。

修复导入内容的一处错误

导入的 tags-tabs-timeline 页里残留了一个 tabs_end 收尾标签 —— 主题并未注册它（只有 tabs / endtabs），导致构建抛出：

1

Nunjucks Error: unknown block tag: tabs_end

删除该行后恢复正常。为此我全量比对了文档用到的全部标签与主题注册标签，确认除它之外没有其它未知标签。

结果

• 构建 72 files，0 error。
• 侧栏 35 条链接全部命中，36 篇文档无孤儿页。
• 搜索索引与 sitemap 各收录 36 条文档。

站点更名

站点名称由「XFM 主题文档」改为 「XFM开源官方文档」，同步更新了这些位置：

重构建后，<title> 与导航栏品牌名均已生效。

主题引用方式：内嵌 → submodule

站点使用 hexo-theme-xfm，该主题源码托管在独立仓库 https://github.com/xfm0797/hexo-theme-xfm。因此本站不应再单独携带一份主题源码，改为以 git submodule 引用：

1
2

git rm -r themes/xfm
git submodule add https://github.com/xfm0797/hexo-theme-xfm.git themes/xfm

效果：仓库中的 themes/xfm 由 72 个内嵌文件 变为 单个 gitlink（模式 160000），锁定上游提交，构建时按 .gitmodules 检出。

1

git clone --recurse-submodules https://github.com/xfm0797/xfm-docs.git

验证

• 仓库确实不再携带主题源码：全新 git clone 后 themes/xfm 为空，执行 git submodule update --init --recursive 后检出主题（73 文件）。
• docs 模式不受影响：上游主题默认 mode: blog，但站点 theme_config.mode: docs 覆盖生效。
• 构建 53 files，0 error。

1

git submodule update --remote themes/xfm

站点初始化

站点基于 Hexo 8，工作目录为 D:/xfm-work/.xfm-smoke/site。初始化时确认了三件事：

1. 依赖完整：站点已装 hexo-renderer-marked、hexo-renderer-ejs 以及 index / archive / category / tag 生成器，可直接 hexo generate。
2. 主题就位：themes/xfm 为 hexo-theme-xfm。
3. 构建可复现：hexo clean && hexo generate 通过。

连接远程仓库

站点初始化为 Git 仓库并绑定远端：

1
2

git init -b main
git remote add origin https://github.com/xfm0797/xfm-docs.git

同时新增 .gitignore，排除 node_modules/、public/、db.json 与 .workbuddy/ 等构建产物与本地数据。

1

GCM_INTERACTIVE=never GIT_TERMINAL_PROMPT=0 git push origin main

配置 docs 模式

站点以双重配置保证运行在 docs 模式：站点 _config.yml 的 theme_config.mode: docs 与主题 _config.yml 的 mode 同时设置为 docs。产物 HTML 上会带 data-mode="docs"，即三栏文档布局。

同时更新了站点标题、描述，并在导航中新增「文档」入口。

解析并生成两套主题文档

内容来源为两套主题仓库的权威资料：

据此整理出 17 篇文档：文档中心 1 篇、hexo-theme-xfm 8 篇、hexo-theme-xongyi 8 篇。侧栏树 source/_data/docs.yml 随之重构为「开始 / hexo-theme-xfm / hexo-theme-xongyi」三段。

踩坑与经验

结果

• 首次提交 101 个文件，已推送 main。
• hexo clean && hexo generate → 53 files，0 error。
• 侧栏树、激活态、上下篇导航、标签插件（note / tabs / row / mermaid）均正常渲染。

下一篇将记录：站点更名与主题引用方式的调整。

排版演示

普通段落包含 加粗、斜体、删除线、内链、外链 与 行内代码。

引用块常用于强调重要观点。
支持多行内容。

列表

• 无序列表项一
• 无序列表项二
  • 嵌套子项
  • 另一个子项
• 无序列表项三

1. 有序列表项一
2. 有序列表项二
3. 有序列表项三

• 已完成任务
• 未完成任务

表格

代码演示

1
2
3
4
5
6

const theme = {
  mode: 'blog',
  features: ['search', 'toc', 'lightbox']
};

export default theme;

1
2

def hello(name: str) -> str:
    return f"Hello, {name}"

标签插件

数学公式

行内公式 $E=mc^2$ 与块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

流程图

图片