配置优先级：

1

主题默认值  <  themes/xfm/_config.yml  <  站点 _config.yml 的 theme_config

检查站点 _config.yml 里是否已有 theme_config 块，它可能覆盖了你改的项。

1
2
3
4

# 站点 _config.yml
theme_config:
  appearance:
    primary: "#ff6b6b"     # ← 这一行会覆盖主题配置里的 primary

YAML 里 false 加引号会变成非空字符串，在 JS 里是真值：

1
2

toc: "false"      # ❌ 实际被当作 true
toc: false        # ✅

主题内部的 bool() 归一化对 'false' 字符串做了特殊处理，但并非所有配置项都走了这条路径。稳妥起见：布尔值不加引号。

用一个 YAML 校验器检查，或直接看 hexo g 的输出有没有解析警告。最常见的三个错误：

1
2
3
4
5
6
7
8
9
10

# ❌ 用了 Tab 缩进
- title: 快速开始
	children:              # Tab 缩进

# ❌ path 少了前导斜杠
    - title: 简介
      path: docs/intro/    # 应为 /docs/xfm/intro/

# ❌ 中英文冒号混用
- title：快速开始          # 中文全角冒号

侧边栏有内容但点击后跳到首页，说明 path 与实际 URL 不一致。

1
2

# 确认页面的真实 URL
ls source/docs/xfm/intro/index.md     # → URL 为 /docs/xfm/intro/

1
2
3

# docs.yml 里必须一致
- title: 主题简介
  path: /docs/xfm/intro/              # ✅

尾部的 / 会被归一化（有无均可），但目录名拼写、前缀缺失会导致失配。

当 docs.yml 不存在、主题自动生成侧边栏时，没有 title 的页面不会出现。给每篇文档补上：

1
2
3
4

---
title: 主题简介
order: 1
---

按顺序检查：

1. 索引里有你搜的内容吗？

1
2

# 直接在索引文件里搜关键词
grep -o '关键词' public/search.json | head

2. 没有 → 内容可能落在 search.content_length 之外（正文后半段不索引），或该页面没有 title
3. 有 → 前端脚本未加载，检查 search.js 是否 404

快捷键由 core.js 全局监听。可能原因：

• 当前档位下搜索被 disable: [search] 之类配置隐藏（搜索没有单独的 disable 键，但 search.enable: false 会移除入口）
• 浏览器扩展占用了 Ctrl+K（某些浏览器把 Ctrl+K 绑定为地址栏搜索）
• 焦点在输入框内——主题的监听仍然有效，但部分扩展会拦截

试试直接用导航栏的 🔍 按钮。

三种方式：

1
2
3
4
5
6
7
8
9
10

① URL 参数（临时，不改任何状态）
   https://example.com/any-page/?__tier=mobile

② 控制台 API（会写入 localStorage 若 remember 为 true）
   XFM.adaptive.setTier('tablet')

③ 锁定整站
   adaptive:
     strategy: fixed
     default_tier: mobile

推荐用 ① URL 参数——不留下持久状态，适合截图与调试。

这是预期行为。strategy: adaptive 时，UA 判定优先于宽度：桌面浏览器即使窗口缩到 400px，UA 仍非移动设备，会按宽度降档；但手机浏览器无论窗口多宽都会被 UA 判定为 mobile。

想让它像传统响应式一样只看宽度：

1
2

adaptive:
  strategy: responsive

1
2
3

adaptive:
  detect:
    upgrade_large_screen: false   # 大屏平板不升级为桌面档

giscus 的三个前置条件缺一不可：

1. 仓库公开
2. 已安装 giscus GitHub App
3. 已在仓库创建对应的 Discussions 分类

到 giscus.app 重新生成配置，核对 repo_id 与 category_id 是否复制完整（这两串较长，容易漏字符）。

1. 确认 vendors.mermaid: true
2. 打开控制台，看是否有动态 import() 失败（同样是 CDN 可达性问题）
3. 检查语法：第一行必须直接是声明语句，不能有空行

1
2
3

graph LR          ← 第一行必须是这个

  A --> B

4. 节点文字含 : () , 时用引号包裹：A["标签: 说明"]
5. 主题的 Mermaid 渲染在 DOMContentLoaded 时触发，若你的内容由 JS 动态插入，图表不会被自动渲染——需手动调用：

1

await window.__xfmLoadMermaid();