绿野 Luye

更新内容

1. 新增文章页大纲导航（响应 Issue #14）：由正文二/三级标题自动生成；宽屏（≥1200px）为文章右侧 sticky 玻璃侧栏，窄屏为浮动按钮 + 右侧抽屉。
2. 滚动高亮当前章节并保持其在列表内可见，页面底部兜底末条；点击条目平滑跳转，复用全局 scroll-padding-top，落点不被固定导航遮挡。
3. 渐进增强与无障碍：toc.js 构建并以 html.toc-ready 门控——禁用 JS、正文标题不足两个或开关关闭时整块不渲染且布局保持单栏；抽屉支持 Esc / 遮罩 / 关闭按钮收起，aria-expanded / aria-controls / aria-label 动态切换并管理开合焦点；尊重系统「减少动态」偏好。
4. 主题设置新增「文章页」组「显示文章大纲」开关（默认开启，未配置按开启处理，老站点升级即生效）。
5. 版本号按 minor 规则升至 1.4.0，README 与 CHANGELOG 同步。

真机验证

环境：Halo 2.26.1 本地真机（H2）+ headless Chrome CDP，41/41 断言通过。

1. 升级安装 1.4.0 保留既有设置，主题 READY；toc.js / style.css 正常下发并带 ?v=1.4.0 缓存破坏。
2. 桌面 1440：双栏网格、sticky 侧栏滚动中段仍固定、8 条目（5×h2 + 3×h3，h4 排除）、标题 id 唯一、scrollspy 中段与底部兜底、锚点落点不被导航遮挡。
3. 移动 390 / 320：浮动按钮可见、抽屉开合、焦点首条 / 归还按钮、body 滚动锁定、条目点击收起并跳转，无横向溢出。
4. 少标题文章整块移除且单栏；既有文章复用原生标题 id；禁用 JS 正文完整且单栏；三档视口控制台零报错。
5. 开关关闭变体包不渲染 toc-col / toc-fab，恢复官方包后回归正常。
6. 临时验证文章已清理，站点恢复 7 篇，全路径 200 / 404 符合预期。

升级方式

1. 下载附件 theme-luye.zip。
2. Halo 后台 → 外观 → 主题 → 升级上传（要求 Halo ≥ 2.26.0）。
3. 升级后大纲默认开启；如需关闭：主题设置 → 文章页 → 显示文章大纲。

附件校验

• 文件数：32
• SHA-256：07a2deca4e07f9fb674f10781731038c0161aa694797c8566154ed7afa7c0e98
• 最低 Halo 版本：2.26.0

相关 PR：#16；关闭 Issue #14。完整历史见 CHANGELOG.md。

在 1.3.3 基础上合并落地一轮性能、无障碍与可维护性优化。相关 PR：#15。

更新内容

1. 锚点修复：修复首页「看看我的文章」等锚点跳转落点被固定导航遮挡的问题，scroll-padding-top 按导航高度 + 12px 偏移（实测落点 88px ≥ 导航 76px）。
2. 无障碍：汉堡菜单动态切换 aria-expanded / aria-controls / aria-label，Esc 关闭并归还焦点；返回顶部尊重系统「减少动态」偏好；分页禁用态改为不可聚焦的 <span>（不再进入 Tab 序），可用态补 rel="prev/next"，移除 javascript: 伪链接。
3. 性能：文章封面、作者头像与 hero 图统一 loading="lazy" decoding="async"；天气画布 resize 防抖 150ms、仅宽度变化时重建粒子。
4. 视觉一致性：单色 SVG 图标改用 CSS mask 着色；行内代码、雾面渐变与滚动条（含 Firefox scrollbar-color）全部由强调色 --green 派生，主题设置改强调色后全站同步生效；补 theme-color meta。
5. 可维护性：置顶大卡抽取为 modules/post-featured.html 片段供列表/网格两分支共用（守卫置于外层 th:block，规避 th:replace 优先级陷阱）；visit-badge 片段自门控「显示文章浏览量」开关，调用方不再重复判断；删除四个冗余叶子 SVG。
6. 与 1.3.2 / 1.3.3 调和：沿用「置顶不要求封面、封面独立可选」语义与精选专题全量已发布筛选（外层 th:block 求值）；无 JS 降级统一为 reveal-ready 机制；保留 1.3.3 阅读排版（摘要 16px / 400、容器 1280px、置顶封面 3.4:1 / 移动端 2:1）。

真机验证

环境：Halo 2.26.1 官方 jar + H2 数据库、无头 Chrome（CDP）。

1. 正式 ZIP 升级安装成功，后台识别版本 1.3.5、主题 READY，既有主题设置保留。
2. 首页、归档、分类、标签、文章、独立页、作者页全路径返回 200，不存在路径按预期 404；多页数据下分页第二页正常（rel="prev/next"、禁用态为 span、无 javascript:）。
3. grid / list 双布局：无封面置顶文章仅渲染一次且不输出空封面图，既有置顶不重复；无封面置顶不进入精选专题。
4. CDP 禁用脚本后，首页 / 分类 / 标签页 .reveal 元素全部可见（reveal-ready 降级生效）。
5. 菜单 aria / Esc / 焦点归还、锚点落点、强调色注入联动 mask 图标与滚动条，逐项复核通过。
6. 1440 / 390 / 320px 三档视口均无横向溢出；控制台无主题侧报错。

升级方式

1. 下载本 Release 附件中的 theme-luye.zip。
2. Halo 后台 → 外观 → 主题 →「绿野 Luye」→ 升级 → 上传 ZIP。
3. 原有主题设置保存在 ConfigMap 中，升级不会丢失。

附件校验

• 文件数：31
• SHA-256：7364919a8918d9c8f4bd97ade33006b4600c7ebf30a31f92eccec39e38e37a29
• 最低 Halo 版本：2.26.0

修复

• 精选专题：从全部已发布文章中筛选带封面的文章，最新 10 篇均无封面时仍能显示较早的封面文章；没有符合条件的文章时隐藏整个区块。变量声明移至外层 th:block，确保 Thymeleaf 按正确顺序求值。
• 无封面置顶文章：置顶大卡不再以封面为必要条件，grid / list 两种布局下均只渲染一次，不输出空封面图，也不重复进入普通文章卡片。
• 无 JavaScript 兜底：仅在 main.js 完成滚动显现初始化后添加 reveal-ready；脚本未加载或未执行时，.reveal 内容保持可见。

新增

• 文章卡片新增浏览量徽章：首页精选专题、置顶大卡、网格卡，以及归档、分类、标签、作者页的文章列表均显示浏览次数。统计由 Halo 内置计数器提供，主题不额外请求接口；可在「主题设置 - 文章列表 - 显示文章浏览量」中一键关闭。

背景

Issue #8 反馈：希望前台能有一个控制台入口（参考 Earth 主题），并且能在主题设置里控制是否放开该入口——避免向前台访客暴露后台地址。

新增能力

位置	表现
导航栏右侧	新增控制台图标按钮 .console-btn，与搜索按钮同规格：38×38 圆形毛玻璃、16px 线性图标、hover 时主题绿描边
页脚联系方式行	新增「控制台」胶囊按钮
主题设置 → 基础	新增「显示控制台入口」开关（默认开启）与「控制台路径」文本（默认 /console）

两处入口共用同一个开关，关闭后同时消失，不留残影。console_path 可自定义，适配修改过后台路径的站点。

改动说明

• settings.yaml：基础组新增 show_console（checkbox，value true）与 console_path（text，value /console）。
• templates/modules/header.html：在 nav-right 区域、search-btn 之后插入控制台按钮。判定条件为 theme.config.basic?.show_console == null or theme.config.basic?.show_console——未配置时按开启处理，老站点从 1.2.0 升级后无需手动保存设置即可看到入口。
• templates/modules/footer.html：联系方式行末尾追加控制台胶囊，判定条件同上。
• templates/assets/css/style.css：
  • .search-btn 选择器扩展为 .search-btn, .console-btn，共用圆角、玻璃底与 focus-visible 描边；
  • @media (max-width:640px)：隐藏导航栏控制台按钮（页脚入口保留）；
  • @media (max-width:480px)（新增断点）：收紧导航间距与内边距、天气图标 30→28px、.logo 改为可收缩、站点名过长以省略号截断。

根因与兜底设计

窄屏溢出（本轮发现并修复）：控制台按钮加入导航栏右侧后，390px 视口下 .nav 实际宽度 417px > 视口 390px，汉堡按钮被切掉；414px 溢出 4px。根因是 .nav-right 为 flex:0 0 auto 不参与收缩，右侧元素总宽超出可用空间。

• ≤640px 隐藏导航栏控制台按钮，窄屏下入口保留在页脚，移动端仍可直达。
• ≤480px 收紧布局并让 .logo 可收缩，站点名过长时省略号截断。

顺带修掉 320px 的既有横向溢出（与本次改动无关，关掉控制台按钮同样溢出）：根因是 .logo 为 flex:0 0 auto 不参与收缩、站点名过长不换行。修复后 320px 下 logo 由 197px 收窄至 138px。

安全兜底：开关缺省为「开启」而非「关闭」——Issue 诉求是「增加入口」，装上即用；不想要的站长一键关掉即可。未登录访问 /console 由 Halo 自身 302 到 /login，主题不接管认证逻辑。

真机验证

环境：Halo 2.26.1（JDK 21），H2 本地实例，--server.port=8090。发版前用正式包 theme-luye-1.3.0.zip 重新升级复验。

1. 正式包升级：POST /apis/api.console.halo.run/v1alpha1/themes/theme-luye/upgrade → 200；主题列表确认 theme-luye 1.3.0 / READY / LayoutTemplateSupported。
2. 包内容断言：28 个关键文件全部齐全；theme.yaml version=1.3.0、requires=2.26.0；settings.yaml 含 show_console / console_path；header.html 含 console-btn 与 /console 兜底；footer.html 含控制台胶囊；style.css 含 .console-btn 样式、≤640 隐藏规则、≤480 断点、省略号截断；README 含 1.3.0 条目与设置表条目——16 项全部通过。
3. 设置项注册：GET /apis/api.console.halo.run/v1alpha1/themes/theme-luye/setting 确认 basic 组含 show_console | checkbox | 显示控制台入口 | true 与 console_path | text | 控制台路径 | /console；升级后 ConfigMap 自动合并默认值。
4. 开启状态：首页渲染 <a class="console-btn" href="/console" aria-label="控制台" title="控制台">，页脚出现「控制台」胶囊。
5. 关闭状态：show_console=false → 导航栏与页脚两处同时消失。
6. 自定义路径：console_path=/my-console → 两处 href 同步变更。
7. 老站点兼容：删除 ConfigMap 中 show_console / console_path（模拟 1.2.0 存量）→ 入口仍按开启渲染，href 回落 /console。
8. 计算样式（无头 Edge + CDP）：桌面 1440×900 与移动 390×844 下 .console-btn 均为 display:flex、38×38、border-radius:9999px、图标 16×16。
9. 导航排布冲突排查（逐视口量 boundingRect）：
   • 1440px：天气组 1138→1242、控制台 1256→1294、联系我胶囊 1308→1392，间距各 14px，三者互不重叠；「联系我」在 ≤860px 已被隐藏，与新按钮无空间竞争。
   • 320 / 360 / 390 / 414 / 480 / 640 / 768 / 900 / 1024 / 1440 十个视口，nav.scrollWidth === nav.clientWidth 且 documentElement.scrollWidth === clientWidth——全部无横向滚动条；开关 ON / OFF 两态各验一遍，结论一致。
10. 全路径扫描：首页 / 归档 / 分类 / 标签 / 关于页 / 文章页 / 归档分页 / 404 页均正常渲染主题布局并包含入口（200/404 状态码符合预期）。
11. 链接可达：GET /console → 302 /login?authentication_required。

兼容性

• 最低要求仍是 Halo ≥ 2.26.0，未使用新 API。
• 主题设置保存在 ConfigMap，升级不丢配置；老站点升级后新增项按开启处理，如需关闭在后台保存即可。
• 未安装任何插件的环境下验证通过，不依赖插件。

升级方式

后台 → 外观 → 主题 →「绿野 Luye」→ 升级 → 上传 theme-luye-1.3.0.zip。

若你不想向前台暴露后台地址，在主题设置「基础」中关闭「显示控制台入口」即可，导航栏与页脚会同时隐藏。

背景

此前主题所有页面共用同一个 <title>（站点标题），既没有 canonical 也没有社交分享标签。对搜索引擎来说首页、文章页、分类页无法区分；文章分享到社交平台时也只有纯文本，没有卡片预览。

新增能力

能力	说明
独立页面标题	首页用站点标题 + 副标题；文章、独立页、分类、标签、作者页各用自己的名称
分页标题	自动追加「第 N 页」，canonical 保留当前页而非一律指向首页
规范链接	每页输出绝对地址的 <link rel="canonical">
Open Graph	og:type / og:site_name / og:title / og:url / og:description / og:image；文章页额外输出 article:published_time 与 article:modified_time
Twitter Card	有封面时 summary_large_image，无封面时 summary
结构化数据	文章页输出 BlogPosting JSON-LD（headline、url、description、image、datePublished、dateModified、author）
个人主页入口	主题设置新增「基础 → 个人主页链接」，填写后在导航栏与页脚显示入口

两个 SEO 开关位于主题设置 → SEO：

• 规范链接和社交分享标签：已由 SEO 插件提供 canonical / OG / Twitter 时关闭，避免重复输出。
• 文章结构化数据：已由插件提供 JSON-LD 时关闭。

两个开关默认开启，且不影响页面标题——标题始终输出。站点 description、文章摘要、分类与标签描述仍由 Halo 侧维护，主题不重复注入同名标签。

其他改动

• error.html 移入 templates/error/ 子目录，对齐 Halo 错误页的模板查找路径。
• 文章封面补 alt（取文章标题）与 decoding="async" / fetchpriority="high"，改善可访问性与首屏加载。
• 修正外站链接的导航高亮：此前会把当前页的 active 状态误加到指向外部域名的链接上。
• 归档页 canonical 同时保留年份与月份。

真机验证

在 Halo 2.26.0 上用正式发布包完成验证，主题显示 1.2.0 / READY，布局契约 LayoutTemplateSupported 正常。

11 条路径的 SEO 标签逐项核对全部通过：每页恰好一个 <title>、一个绝对地址 canonical、无重复 description；OG 与 Twitter Card 完整；文章 JSON-LD 可被正常解析，@type=BlogPosting，headline 与作者与正文一致；有封面时 twitter:card 为 summary_large_image，无封面为 summary。

页面	标题	canonical	og:type
首页	站点标题（+ 副标题）	/	website
首页第 2 页	…- 第 2 页	/page/2	website
归档	文章归档 - …	/archives	website
归档分页	文章归档 - 第 2 页 - …	/archives/page/2	website
文章详情	文章标题 - …	/archives/{slug}	article
分类 / 标签	分类名 - …	/categories/{slug}	website
作者页	作者名 - …	/authors/{name}	profile
404	资源不存在 - …	不输出	—

两处风险点已专项验证：

1. error.html 移入子目录后 404 页是否仍正常 —— 正常渲染，<title> 正确、robots noindex 生效、样式无破损（附无头浏览器截图核验）。已用 1.1.2 的包回滚做对照，确认某些请求返回 JSON 是Halo 的既有行为，与本次改动无关。
2. 归档末页 nextUrl 为空时路径拼接是否报错 —— 实测末页渲染正常，canonical 正确回退到 /archives，无异常。

视觉回归：首页与 404 页截图均无异常。静态校验：两个 YAML 文件解析通过，17 个模板标签闭合检查全部通过。

升级方式

1. 下载本 Release 附件中的 theme-luye-1.2.0.zip
2. Halo 后台 → 外观 → 主题 → 找到「绿野 Luye」→ 升级 → 上传 zip
3. 如主题设置显示不全，点击「重载主题配置」以加载新增的 SEO 与基础分组

原有主题设置保存在 ConfigMap 中，升级不会丢失。升级后建议强制刷新浏览器（Ctrl/Cmd + F5）清除缓存的 HTML/CSS。

若你已安装 SEO 插件，请到主题设置 → SEO 关闭对应开关，避免与插件重复输出相同标签。

兼容性

Halo >= 2.26.0，与前序版本一致。本次无破坏性变更。

现象

安装并启用 highlight.js 代码高亮 或 Shiki 代码高亮 插件后，代码块的插件配色不生效：代码块背景与文字被压成主题的深绿/浅绿，语法着色几乎看不出来。

根因（CSS 层）

1. .post-content code
   
   无条件设置了 background:rgba(125,217,166,0.10); color:#A9E8C6——插件注入的 hljs 类代码块同样命中这条规则，插件的整套文字配色被主题绿覆盖。
2. .post-content pre 设置了 background:#0A1712，插件代码块的背景同样被盖住。
3. 页面没有向插件声明配色方案，Shiki 这类按页面配色选择暗色高亮主题的插件无法判断该用哪套配色。

修复内容

位置	修复前	修复后
行内/块级代码配色	.post-content code 无条件上色	.post-content code:not(.hljs)，绿色仅作未高亮内容的兜底
代码块容器背景	.post-content pre 无条件深绿底	新增 .post-content pre:has(>code.hljs){background:none}，已高亮的代码块让出背景
块内代码文字色	.post-content pre code 无条件上色	.post-content pre code:not(.hljs)，插件已接管时完全不干预
页面配色声明	无	<html data-color-scheme="dark">，供 Shiki 等插件识别深色外观

行为说明

• 未安装插件：普通代码块与行内代码仍保持绿野的深绿配色，主题风格不变。
• 已安装并高亮：code.hljs 的背景与文字色完全由插件主题接管，主题不再干预；语法着色正常显示。
• 编辑器与前台：主题不会自动同步编辑器配色。使用 Shiki 时，将插件的「编辑器设置 → 高亮主题」与「基本设置 → 暗色主题」设为同一配色。

真机验证

已在 Halo 2.26.0 本机实例上用正式发布包完成验证：

• 主题升级返回 200，已装版本显示 1.1.2 / READY，布局契约 LayoutTemplateSupported 正常。

• Halo 实际提供的 style.css（非仅开发态）确认包含全部三条修复规则。

• 无头浏览器读取计算样式：

  元素	1.1.1（修复前）	1.1.2（修复后）
  pre:has(code.hljs) 背景	rgb(10,23,18)（被主题覆盖）	rgba(0,0,0,0)（让出给插件）
  code.hljs 背景	rgba(0,0,0,0)	取插件配色
  code.hljs 文字色	rgb(199,227,210)（主题绿）	取插件配色
  未高亮 pre 背景	rgb(10,23,18)	rgb(10,23,18)（兜底不变）

  对照实验直接证明：同一段 HTML 加载两个版本的 CSS，1.1.2 确实把配色让给了插件，而未高亮代码块的主题绿兜底不受影响。

• document.documentElement 的 data-color-scheme 读取为 dark。

• 全路径扫描全部正常：首页、分页、归档、分类、标签、文章详情（含代码块验证页）、作者页均返回 200，404 页返回 404。

兼容性

Halo >= 2.26.0，与前序版本一致。CSS 使用了 :has() 选择器，现代浏览器均已支持（Halo 后台与主流现代浏览器环境无兼容问题）。

升级方式

1. 下载本 Release 附件中的 theme-luye-1.1.2.zip
2. Halo 后台 → 外观 → 主题 → 找到「绿野 Luye」→ 升级 → 上传 zip
3. 主题设置保存在 ConfigMap 中，升级不会丢失配置

若升级后代码块仍显示旧样式，请强制刷新浏览器（Ctrl/Cmd + F5）清除缓存的 CSS。

• 修复首页「精选专题」区文章封面不显示的问题。

深绿玻璃拟态 Halo 主题的首次功能升级：首页从「Hero + 纵向文章流」升级为完整的信息层次体验。

功能特性

• Hero 数据徽章行：文章 / 分类 / 标签真实统计数字，琥珀色 #E8B96E 斜体衬线点缀，访问量可选配置
• 精选专题区：自动取最近 3 篇带封面文章生成玻璃特色卡
• 文章列表混合布局：置顶文章通栏大卡（左封面右内容）+ 双列网格，可在主题设置切回经典纵向列表
• 首页作者卡片：圆头像徽章 + 简介 + GitHub/Email 联系胶囊
• 导航搜索入口：配置搜索页链接后显示（可选）
• 新增主题设置分组：精选专题 / 文章列表 / 作者卡片 / Hero 徽章，全部带默认值兜底，老站点升级免配置

修复

• 修复首页数据徽章 categoryFinder.getAll() 调用不存在的 API 导致的 500（改为 list(1, 1).total）

安装方式

1. 下载本 Release 附件中的 theme-luye.zip
2. Halo 后台 → 外观 → 主题 → 升级主题（或安装主题）
3. 在「主题设置」中查看新增的配置分组

兼容性

• Halo >= 2.26.0
• 已在 Halo 2.26.0 本地实例完成真机验证（首页 / 文章 / 归档 / 分类 / 标签 / 静态资源全路径 200）

绿野 Luye 主题首个发布版本，要求 Halo ≥ 2.26.0。

深绿玻璃拟态风格：雾绿光晕、毛玻璃卡片、衬线大标题，视觉语言移植自 Ron567 个人主页
晴 / 雨 / 雪三种 Canvas 粒子背景特效，导航栏一键切换
完整模板：首页（Hero + 文章列表）、文章页、独立页、「关于我」自定义模板、归档、分类、标签、作者页、404
主题设置：Hero 文案与横幅图、强调色、天气/字体开关、页脚信息
安装：下载下方 theme-luye.zip，在 Halo 后台 → 外观 → 主题 → 安装主题中上传即可。