这两天的主线是和上游主题的一次往返:10-13 我在站点层临时规避的问题,10-14 就被上游收编成原生修复,补丁随之退役。同时新版本带来两个新能力,需要站点侧各补一行配置。

一、站点层又回到「零补丁」

时间 主题版本 站点级补丁文件数 说明
10-11 及以前 v1.0.0 10 个 文档树、tabs、分页、挂件滚动、笔记过滤、菜单顺序…全靠站点补
10-12 v1.1.0 0 上游 95ede28 一次性修掉 9 个缺陷,补丁全部移除
10-13 v1.2.0 1 → 0 新增语言切换与 AdSense;当天加的 P9 补丁今天退役
10-14 v1.3.0 0 手机端导航原生修复 + 悬浮按钮组

现在 _config.yml 里只剩原生配置,没有任何自定义 CSS / JS 文件。

二、手机端菜单按钮:从站点补丁到上游修复

症状

手机端导航栏左侧的汉堡按钮既看不见也点不动。

根因

用 Chrome DevTools 协议在 iPhone 视口(390×844)下真实渲染才看出来:按钮的 DOM、图标、点击事件全都在,display 是 grid、visibility 是 visible,但 getBoundingClientRect().width 是 0 —— 按钮中心的 elementFromPoint 命中的是 .header-inner,于是”看不到”和”点不动”是同一个原因。

问题出在主题 .header-inner 的 flex 布局:

子项 flex 窄屏下的表现
.brand(logo + 标题) 0 0 auto 不可收缩 不动
.nav-tools(搜索 / 语言 / RSS / 深浅色) 0 0 auto 不可收缩 被挤出视口右缘
.nav-toggle(菜单按钮) 0 1 auto 唯一可收缩 吸收全部溢出 → 38px 变成 0

手机档内容总需求约 430px,可用只有 362px,40 多 px 的收缩量 100% 落在按钮上。这类问题静态读 HTML 和 CSS 是发现不了的,必须真机口径渲染。

两轮修复

10-13 站点层(P9):新增 source/css/xfm-mobile-nav.css,给按钮加 flex: 0 0 auto,并把 .brand 改成可收缩 + 标题省略号,让溢出量由站点标题吸收。

10-14 上游 783863e(v1.3.0):主题原生修好了,而且比我的补丁更完整 —— 除了同样的 flex: none 与品牌区收缩,它还给 logo / mark 加了 flex: none 保底、给品牌区设 min-width: 34px、顺手把 .nav-fab 从 inline-grid 改成 inline-flex(此前图标与文字被排成了两行)。

于是 source/css/xfm-mobile-nav.css 直接删除,custom.css 回到空数组。

退役后验证(CDP 真机口径)

档位 菜单按钮 点击抽屉 横向溢出
mobile 390px 38px 显示 可开 0
mobile 320px 38px 显示 可开 0
tablet 900px 38px 显示 可开 0
desktop 1440px display: none(横排菜单正常) — 0

覆盖首页 / 博客文章 / 文档页 / 笔记文章 / 笔记索引 / 归档六类页面,结果一致。

三、顺带补上的两个缺口

1. 笔记模式在手机上打不开侧栏

v1.3.0 新增了右下角悬浮按钮组 floating,其中「文档目录」按钮默认只在文档模式出现(toc_modes: [docs])。但本站的笔记文章是 mode: notes,窄屏下左侧笔记导航是 offcanvas —— 没有这个按钮就根本打不开笔记树。

主题在配置注释里正好点明了这个场景,于是站点加一行:

YAML
1
2
3
theme_config:
floating:
toc_modes: [docs, notes]

验证:手机档笔记文章出现目录按钮,点击后侧栏展开 320px,6 条笔记链接齐全;博客文章仍不显示该按钮(本就没有侧栏)。

2. 全站默认形态被误改成 docs

theme_config.mode 曾被改成 docs,这会让首页和博客文章全部退回三栏文档形态、右侧挂件栏消失。该错误值随 10-13 的提交推到了远端,今天已改回 blog。

记一笔

形态配置属于一改就全局变形的开关。以后改动 _config.yml 后,形态抽查要作为固定回归项 —— 光看构建成功是挡不住的。

四、新版本带来的能力

  • v1.2.0:导航栏中英切换(lang_switcher,界面文案切换,正文不参与)、Google AdSense 广告位。
  • v1.3.0:右下角悬浮按钮组(目录、回到顶部);并修复了 v1.2.0 引入的一个严重缺陷 —— 语言选项按钮的 data-lang 属性与 <html> 上的同名属性冲突,i18n 的点击委托误命中 <html>,会导致全站链接点击失效。本次已验证:切换语言前后,站内链接跳转均正常。

五、当前站点定制清单

只剩 _config.yml 里的原生配置:

目的 配置
全站默认形态 mode: blog(文档页 docs、笔记文章 notes 各自覆盖)
文档树默认收起 docs.expanded: false + auto_expand: true
菜单顺序 menu_order: [首页,归档,分类,标签,文档,笔记,更多]
笔记收录范围 notes.note_categories: [更新日志]
挂件栏不被裁剪 sidebar.sticky: false
笔记模式也有目录按钮 floating.toc_modes: [docs, notes]

custom.css / custom.js 注入槽位保留为空,供日后再打补丁时使用。

相关阅读