项目: Blog-Hexo (Butterfly 主题定制)
阶段: 代码阅读与目录跳转修复
提交范围: 18d27c5 至 10e4a3a
关键文件: code-highlight.css / typography.css / responsive.css / themes/butterfly/source/js/main.js

目录

  • 提交范围
  • 优化目标
  • 代码主题对齐
  • 目录跳转偏移
  • 实时目录锚点映射
  • 影响范围
  • 验证要点
  • 后续建议

提交范围

提交 日期 说明
18d27c5 2026-07-12 对齐 VS Code Dark+ 代码主题与字体
4f77f3c 2026-07-12 统一目录跳转与标题定位偏移
10e4a3a 2026-07-12 改用实时目录锚点映射机制

优化目标

技术博客的核心阅读对象不是普通段落，而是：

  • 代码块。
  • 文件路径。
  • 函数名。
  • 表格。
  • 长文目录。

本阶段主要解决：

  • 代码块颜色和本地 VS Code 阅读习惯不一致。
  • 目录点击后标题定位被固定导航遮挡。
  • Butterfly 目录锚点在页面结构变化后映射不稳定。

代码主题对齐

涉及提交：

  • 18d27c5

涉及文件：

  • _config.butterfly.yml
  • source/css/modules/code-highlight.css

1. 目标风格

暗色代码块对齐本地常用编辑器体验：

  • VS Code Dark+
  • Cascadia Code
  • 16px 左右阅读字号
  • 清晰 token 色彩

2. 关键调整

code-highlight.css 调整内容：

  • 代码块背景。
  • 工具栏背景。
  • 行号颜色。
  • token 颜色。
  • 字体族。
  • 行高。
  • 行内代码样式。

核心字体栈：

1
font-family: "Cascadia Code", "Cascadia Mono", Consolas, "Courier New", monospace;

3. 设计原因

博客文章包含大量：

  • C 语言代码。
  • SDK 路径。
  • 宏定义。
  • 函数名。
  • 架构片段。

代码块越接近本地 IDE 阅读体验，迁移到网页后的认知成本越低。

目录跳转偏移

涉及提交：

  • 4f77f3c

涉及文件：

  • source/css/modules/responsive.css
  • source/css/modules/typography.css
  • themes/butterfly/source/js/main.js

1. 问题表现

点击文章目录后，标题定位容易被固定导航遮住。

原因：

  • 页面存在固定导航栏。
  • 标题锚点默认滚动到视口顶部。
  • 移动端和桌面端导航高度不同。

2. CSS 侧调整

通过 scroll-padding-top 和标题定位策略，让跳转位置预留导航高度。

相关文件：

1
2
source/css/modules/typography.css
source/css/modules/responsive.css

3. JS 侧调整

Butterfly 的目录点击逻辑位于：

1
themes/butterfly/source/js/main.js

提交 4f77f3c 对目录跳转逻辑做了第一次统一，避免不同入口计算偏移不一致。

实时目录锚点映射

涉及提交：

  • 10e4a3a

涉及文件：

  • themes/butterfly/source/js/main.js

1. 为什么需要实时映射

文章内容较长，且标题结构可能包含：

  • H1/H2/H3 多级标题。
  • 自动生成的 anchor。
  • 中文标题。
  • 代码、表格、长段落导致的滚动高度变化。

如果目录只在初始化时缓存锚点映射，页面后续变化可能导致：

  • 当前目录高亮不准确。
  • 点击目录跳到错误位置。
  • 标题偏移和实际 DOM 不一致。

2. 实时映射机制

提交 10e4a3a 将目录锚点逻辑改为实时查询：

  • 点击时根据当前 DOM 查找目标标题。
  • 滚动时根据当前标题位置更新目录状态。
  • 避免依赖过早缓存的锚点映射。

3. 改动收益

  • 长文目录稳定性更好。
  • 中文标题锚点更可靠。
  • 页面加载后发生布局变化时，目录仍能工作。
  • 与固定导航偏移策略配合更自然。

影响范围

页面 影响
文章页 代码块主题、目录跳转、标题定位
移动端文章页 目录抽屉与标题定位
长文页面 当前目录高亮和滚动定位
技术文档 代码可读性提升

验证要点

1. 代码块

检查：

  • 暗黑模式代码块是否接近 VS Code Dark+。
  • 字体是否为 Cascadia Code 优先。
  • 行号是否清晰。
  • 选中文本是否可读。
  • 行内代码是否和正文区分明显。

2. 目录点击

检查：

  • 点击目录一级标题。
  • 点击目录二级标题。
  • 点击目录三级标题。
  • 标题是否被导航遮挡。
  • URL hash 是否更新正常。

3. 滚动高亮

检查：

  • 手动滚动文章。
  • 当前目录项是否跟随变化。
  • 长文中段和末尾是否仍准确。

后续建议

1. 减少主题源码改动

themes/butterfly/source/js/main.js 已被本地修改，后续升级 Butterfly 时需要重点合并。

建议后续记录：

1
themes/butterfly/source/js/main.js

中的本地补丁点。

2. 增加目录视觉层级

目录功能已稳定，视觉上还可以继续：

  • 当前项左侧加细线。
  • H2/H3 缩进更明显。
  • 长标题截断更平滑。

3. 优化代码块复制反馈

后续可以增加：

  • 复制成功提示。
  • 复制按钮 hover 状态。
  • 移动端复制按钮更大点击区域。

结论

本阶段把技术博客最关键的两个阅读组件继续打磨：

  • 代码块更接近本地开发体验。
  • 长文目录跳转和高亮更可靠。

这类优化不一定第一眼显眼，但会显著影响读者阅读长篇工程文档时的稳定感。