之前写更新日志,都是「今天改了什么」的流水账。这次换个角度:把主题仓库里 tag 之间的提交全部拉出来,按版本重新读一遍,看看这五个版本到底在解决什么。

从 10-11 首版到 10-19 的 v1.4.0,一共 5 个版本、24 个提交,累计 49 个文件、+4212 / −610 行。有意思的是,主线并不是「功能越堆越多」,而是一条不断把站点层补丁收回主题本体的线。

一、五个版本一览

版本 日期 提交 改动规模 这一版的主线
v1.0.0 10-11 7 33 文件 · +2819 / −206 从零立起三模式骨架,响应式改自适应
v1.1.0 10-12 3 19 文件 · +560 / −95 一次收编站点层规避的 9 个缺陷
v1.2.0 10-13 4 23 文件 · +1221 / −18 中英切换与 AdSense 广告位
v1.3.0 10-14 5 12 文件 · +223 / −39 手机端抽屉按钮归零、悬浮按钮组
v1.4.0 10-19 5 13 文件 · +873 / −112 导航栏升为多级菜单
三模式首版

一套代码同时产出 blog / notes / docs 三种形态,响应式改为三档自适应。

收编站点补丁

侧栏折叠、选项卡、笔记过滤、分页、挂件栏等 9 个缺陷回归主题本体。

双语与广告

导航栏中英切换、运行期界面语言替换、Google AdSense 广告位。

手机端修复

抽屉档菜单按钮被 flex 压成 0 宽的问题原生修复,新增悬浮按钮组。

多级导航

导航栏支持三级菜单,新增 nav 配置节;顺手修掉档位规则与版权占位符。

二、v1.0.0 · 先立骨架

首版只做一件事:让一套模板同时撑起三种形态。layout.ejs 按 page.mode || theme.mode 分发,blog 走列表 + 挂件栏,notes 走左侧笔记树,docs 走三栏文档布局。

真正费工夫的是自适应。之前的写法是媒体查询里逐条改样式,档位一多就互相打架;这版改成三档独立令牌——手机 / 平板 / 桌面各自一套尺寸、间距、字号变量,细节规则按档位分别生成,而不是在一份样式上不断覆盖。

同版还收掉了三个小问题:语言占位符没替换、文档翻页到最后一页时出现空白翻页条、笔记侧栏的当前分类重复出现两次。

三、v1.1.0 · 把补丁收回本体

这是五个版本里含金量最高的一版。背景很具体:站点为了能上线,在主题外面写了 overrides、scripts、custom.css 一堆规避文件,主题一升级,补丁全废。与其维护这层壳,不如把能力补回主题。

站点补丁 收编后在主题里的形态
P1 文档侧栏不能折叠 has-children 两列栅格 + 纯 CSS 收起态,expanded / auto_expand / toggle_label 三个配置真正生效
P2 选项卡点不动 模板只产出了 DOM 和样式、没有切换逻辑,补上按钮与面板联动、方向键导航、aria-selected 同步
P3 笔记侧栏收录混乱 新增 note_categories / note_tags 过滤(同时配置取交集),group_by: none 支持平铺,collapsed 从死配置变活
P4 首页与末页页码偏移 翻页组件始终输出「上一页 / 下一页」,不可用时给禁用态占位,不再左右跳位
P5 挂件被裁掉 去掉挂件栏的 max-height / overflow-y,不再出现侧栏自己的滚动条把下方挂件切掉
C7 无标题页右侧空栏 目录栏增加「页面真有 h2–h4 标题」判定,没有就整栏不渲染
C2 Waline v2 不认配置 评论区把 snake_case 选项归一成驼峰(server_url → serverURL 等),v2 才认

一次提交、17 个文件、+490 / −93,站点的自定义目录当天就清空了。事后看,这版定下了一条规矩:能在上游修的,绝不留在站点层。

四、v1.2.0 · 双语与广告

两个新能力,都是「配置即用」型:

  • 界面语言:导航栏加中英切换,运行期替换界面文案,不用重载页面。
  • AdSense:支持挂 AdSense 广告,广告位可在配置里声明位置与尺寸。

改动量不小(+1221 行),因为语言包要按主题里所有文案逐条抽出来。不过它也埋了个雷:语言选项的属性写法误命中了页面根元素,导致全站链接点不动——下一版就修这个。

五、v1.3.0 · 手机端那个「消失」的按钮

症状是手机端导航栏左侧的汉堡按钮既看不见也点不动。DOM 在、图标在、事件也在,display 和 visibility 都正常,但它的宽度算出来是 0。

根因在头部 flex 布局:品牌区与工具区都设了不收缩,唯一允许收缩的菜单按钮成了溢出量的「垃圾桶」,38px 被压到 0。

这版的原生修复做得比站点临时补丁更全:按钮固定不收缩、品牌区可收缩并带 min-width 保底、logo 不参与压缩,顺带把悬浮按钮从 inline-grid 改成 inline-flex(此前图标和文字被排成两行)。

同期还有两件事:修掉上版遗留的全站链接失效问题(属性误命中根元素),以及新增右下角悬浮按钮组——回到顶部、深浅色切换,文档页多一个「文档目录」按钮,手机上尤其实用。

六、v1.4.0 · 导航栏长出了第三层

本站正好是这版的重度用户:现在顶部是「文档 → 教程 → TypeScript」三级菜单。之前菜单只能平铺,多出来的层级只能挤进一个页面里的锚点。

v1.4.0 给菜单加了 children 嵌套,并配了一个 nav 配置节:

配置项 默认值 作用
depth 3 最多渲染几级:1 只有一级,2 一级 + 下拉,3 下拉里再往右飞一层
trigger hover 桌面展开方式,hover 悬停展开、click 点箭头才展开(触屏一律走点击)
hover_delay 120 悬停移出后的收起延迟,单位毫秒,0 为立即收起
submenu_width 190 子菜单最小宽度,二级下拉与三级右飞共用
drawer_accordion true 窄屏抽屉里的形态:true 可折叠分组、false 全部拉平按层级缩进

菜单项的写法有两种语义,容易搞混:

  • 只写 children 不写 path —— 这一项本身就是展开按钮,点了不跳转;
  • path 与 children 都写 —— 点击跳转,右侧的箭头单独负责展开。

本站的三级菜单就是这么写的:

YAML
1
2
3
4
5
6
7
8
9
10
文档:
path: /docs/
icon: file-doc
children:
教程:
icon: folder
children:
TypeScript:
path: /docs/ts/
icon: file-doc

教程 只当分组用(没有 path),点击只展开不跳转;TypeScript 才是真正的链接。层级超过 nav.depth 的部分会被截断,所以改结构时记得对一眼这个值。

同版还夹了两个修复。一个是版权声明里的 {link} 占位符:替换结果是一段链接标签,原先用转义输出,页面上直接显示成字面代码,改成原样输出才对。另一个是自适应档位规则的老毛病——细节样式直接拼在选择器前面,一段逗号列表里只有第一个选择器带了档位前缀,后面的全变成全局规则。比如一条本该只作用于手机档的三列网格规则,把桌面端的友链也压成了一列。修法是按顶层逗号拆分(括号里的逗号不动),逐个选择器补前缀;顺手给手机档加了分页降级,390px 下只保留上一页 / 下一页,不再被一长串页码撑破布局。

七、升级要注意什么

主题既可以 npm 装,也可以像本站这样用 git submodule 锁版本(当前锁在 ccb49a7 = v1.4.0)。从旧版本升上来的话,只有三处值得留意:

  1. v1.1.0 之后:之前写在站点层的 overrides / scripts / custom.css 该逐条删掉了,能力已经在主题里,留着反而互相覆盖。
  2. v1.2.0 之后:Waline 的配置键用驼峰写法(serverURL / requiredMeta / pageSize),旧写法虽然兼容,但会让人误以为是新版不认配置。
  3. v1.4.0 之后:既有菜单不用改,不写 nav 节就走默认值;要做多级才加 children,注意 depth 与 drawer_accordion 的搭配。

判断「这个需求该不该进主题」的两条土办法:一看它是否需要站点重复写同样的规避代码,二看它是否属于主题自身的渲染职责。两条中一条成立,就该往上收,而不是在站点层打补丁。

八、写在最后

五个版本看下来,代码量涨得不快(+4212 行里还有一大半是语言包和文档),但站点层的自定义文件从十几个变成了零。这件事比多加几个功能更值——主题升级不再意味着重新对一遍补丁,锁个版本、拉一下 submodule 就能跑。

下个版本想做的还是这个方向:把配置里那些「必须读源码才知道怎么写」的地方,都变成带注释的默认值。