halo-theme-cosolar v1.1.8

更新速览

类型	内容
✨ 新功能	侧边栏新增「广告位」模块，可填写任意 HTML 展示自定义广告
🎨 样式	doc 阅读页顶部「返回」按钮美化：渐变底、悬停浮起投影与箭头滑动动效
🎨 样式	广告位标题图标更换为内置 SVG，跟随主题色

1、侧边栏广告位模块（src/partials/sidebar.html · settings.yaml · src/css/main.css）

在首页 / 列表页侧边栏新增可配置的「广告位」模块，用于展示自定义广告：

• 广告内容支持任意 HTML（图片、链接、站外广告代码等），在「侧边栏设置 → 侧边栏模块顺序」中添加「广告位」，并在「广告位」设置组开启、填写标题与内容（标题留空则不显示标题栏）。
• 内容样式做了基础适配：图片 max-width:100% 自适应圆角、链接取主题色、代码块内部滚动，明暗主题均兼容。
• 图标：广告位标题图标使用内置 SVG 且 fill=currentColor，自动跟随标题栏主题色。

2、阅读页返回按钮美化（src/css/doc.css）

• doc 阅读页顶部「← 返回」按钮优化：底色由纯色改为「白 → 浅青」柔和渐变并带极轻投影；悬停时按钮轻微上浮、浮现主题绿色光晕投影，返回箭头向左滑动；按下时轻微收缩，交互反馈更生动。

halo-theme-cosolar v1.1.7

更新速览

类型	内容
✨ 新功能	阅读页侧边栏知识库图标替换为内置书本 SVG（主题色、无背景框）
✨ 新功能	知识库名称 / 描述截断时悬停气泡展示完整内容
✨ 新功能	右栏文档大纲默认展开一级标题的子级
🎨 样式	友链导航图标重构：去除原背景，统一青绿主题镂空图标与选中高亮
🎨 样式	分类导航图标等页头复用样式细化，视觉统一
🐛 修复	引入 KaTeX 样式表，修复含公式文档的渲染排版
🔧 调整	Halo 最低版本由 2.25 上调至 2.26

halo-theme-cosolar v1.1.6

新增功能

主题接入了「知识库」功能——可以把成套的文档像书一样组织起来给访客阅读；同时优化了页脚在极简模式下的留白，并让部分插件页面自动拥有和站点一致的外观。

项目	说明
主题版本	1.1.6
发布日期	2026-08-30
Halo 版本要求	>= 2.25.0（较此前上调，升级前请确认 Halo 已达标）
是否需要重新配置	不需要，原有主题设置完整保留
是否需要装插件	仅「知识库」功能需要 plugin-minidocs，不装也不影响博客

✨ 新增 1：知识库功能（列表页 + 三栏阅读页）

配套 MiniDocs 插件后，你的站点可以多出两个页面：

• 知识库列表页 /docs：像书架一样展示你所有的知识库。
• 知识库阅读页 /docs/view/{知识库}：像看电子书一样浏览文档。

列表页能做什么

• 顶部统计看板：知识库总数、文档总数、标签数量、访问量、点赞量。
• 搜索（按 / 键即可聚焦）与标签筛选，支持四种排序：最近更新 / 文档最多 / 名称 A-Z / 最新创建。
• 卡片视图与列表视图一键切换；内容多时自动分页。
• 左侧边栏展示「今日动态」（今日更新数、文档总数、贡献者）、「最近更新」和「标签云」，点标签即可筛选。
• 卡片可直接点赞，访客无需登录（浏览器本地记录，避免重复点赞）。

阅读页能做什么

• 三栏布局：左边文档目录树、中间正文、右边文章大纲。
• 点目录直接换文章，不刷新页面，翻文档时不会被打断阅读节奏；地址栏同步变化，方便复制分享。
• 目录树可搜索、可折叠，当前文档自动高亮并展开所在层级。
• 右侧大纲跟随滚动自动高亮所在章节，支持分组展开 / 收起，点击即平滑跳转。
• 代码块带语言标签和一键复制按钮；mermaid 图表支持「预览 / 源码」切换。
• 两侧栏宽度可拖拽：文档树 200–520px、大纲 170–480px，宽屏窄屏都能调到舒服的比例。
• 底部信息栏显示文档路径、字数、行数、作者与创建 / 更新时间。
• 顶部工具条提供：返回知识库、加入浏览器书签、复制链接、点赞、访问量。
• 完整支持暗色主题与手机浏览。

怎么开启

1. 安装并启用 plugin-minidocs 插件（下载：halo-plugin-minidocs Releases）。
2. 在插件设置中开启「允许未登录用户阅读」（希望游客也能看的话）。
3. 在后台创建至少一个公开知识库，并在其中发布至少一篇文档。
4. 访问 /docs 即可看到效果，无需在主题里额外开关页面。

不需要知识库功能？不装插件即可，博客其他部分完全不受影响，只是 /docs 不可访问。

可以设置什么

在 主题设置 → 知识库页设置 中：

设置项	作用	默认
显示统计栏	列表页顶部的五项数据看板	开
显示左侧边栏	列表页的今日动态 / 最近更新 / 标签云	开
最近更新显示条数	侧栏「最近更新」显示几条，超出内部滚动	5
标签云显示条数	侧栏「标签分类」显示几个标签，超出内部滚动	10

---

✨ 新增 2：插件页面自动沿用站点外观

主题适配了 Halo 2.26 的「页面布局契约」。简单说：部分支持该能力的插件，其前台页面会自动带上你站点的页头、页脚、主题色与暗色模式，不再出现「点进插件页面突然换了套皮肤」的割裂感。

• 无需任何配置，升级主题后自动生效。
• 在 主题管理 中查看主题状态时，布局契约一项会显示为「支持」。

---

🐛 修复

• 关闭「页脚主区域」后，底部版权条上下不再出现大片空白，分割线也一并隐藏，极简页脚更紧凑。

💄 细节优化

• 知识库卡片上的标签徽标改为青绿主题色，与站点配色统一。

---

⬆️ 升级指南

1. 确认 Halo 版本 ≥ 2.25.0（后台「关于」或系统信息查看）。低于该版本请先升级 Halo，否则主题会提示版本不满足。
2. 从 Releases 下载 halo-theme-cosolar-1.1.6.zip。
3. 进入 后台 → 主题管理 → 安装主题，上传 ZIP；若提示已存在，可先卸载旧版再安装，或直接覆盖安装。
4. 启用后无需重新配置，原设置项完整保留；新版本只新增了「知识库页设置」分组。
5. 首次使用知识库功能，请先完成上面「怎么开启」的 4 步。

❓ 升级后常见问题

升级提示「Halo 版本不满足」怎么办？

把 Halo 升级到 2.25.0 及以上即可。这是本次唯一一项硬性要求变化。

/docs 打不开或列表是空的？

按顺序检查：① 已安装并启用 plugin-minidocs；② 插件设置已开启「允许未登录用户阅读」；③ 至少有一个公开的知识库；④ 库内至少有一篇状态为已发布的文档。

阅读页点目录没反应 / 提示无权限？

阅读页优先走公开接口；若是私有知识库，需要已登录且有权限的账号才能查看，未登录会提示「无权限查看该文档」。

只想安安静静写博客，可以不用知识库吗？

完全可以。不安装 plugin-minidocs 时，主题所有原有功能不受影响，也不会多出任何入口。

---

历史版本

更早版本的变更记录见 GitHub Releases。

知识库预览

halo-theme-cosolar v1.1.5

1. 页脚 legal 链接开关修复

恢复此前被误 git checkout 还原的修复。将 legal 链接（隐私、条款、友链、关于）的开关判断从错误的 Elvis 写法 ?: true ? 改为正确的 ? 条件判断，确保开关关闭时不显示对应链接。

2. 移动端抽屉导航顶栏固定

修复打开抽屉（汉堡菜单）后顶部导航栏消失/被卷走的问题。在 @media (max-width: 768px) 内新增：抽屉打开时强制 .site-header 固定在最上层。

层叠关系：.site-header (z-index 101) > .header-nav 抽屉 (z-index 100) > .nav-backdrop (z-index 99)。

3. 移动端抽屉左侧灰色边框修复

DevTools 显示抽屉左侧存在 8px 灰色间隙，根因为桌面端 .header-nav { margin-left: 8px } 在移动端未被重置。在移动端 media query 内的 .header-nav 增加 margin-left: 0，消除左侧留白。

4. 友链简洁模式名称溢出省略

友链简洁模式下名称过长时改为省略号截断，避免溢出。

halo-theme-cosolar v1.1.4

图库页面 (Photos) 体验增强

新增两项图库设置，让访客可以更灵活地浏览照片。

• 悬停显示图片信息（photos_show_meta，默认开启）：
  • 鼠标移动到图片上时，在图片底部叠层显示照片名称与所属分组信息。
  • 读取路径：theme.config?.photos?.photos_show_meta。
• 点击图片行为（photos_click_behavior，默认 detail）：
  • detail（跳转详情页）：点击图片进入照片详情页；悬停时同时显示「查看详情」与「放大查看」两个按钮。
  • lightbox（直接放大查看）：点击图片直接打开大图灯箱，不再跳转详情页，此时「查看详情」按钮自动隐藏，仅保留「放大查看」。
  • 读取路径：theme.config?.photos?.photos_click_behavior。
• 配套更新 photos.css / photos.ts / photo.html / photos.html 与 main.css，实现叠层样式、按钮显隐逻辑与灯箱交互。
• theme.yaml 版本号升至 1.1.4。

登录注册页

• 修复登录注册页样式问题；
• 修复文章内容引用块多一行空行；

halo-theme-cosolar v1.1.3

页脚设置重构

将页脚相关设置统一收归至「页脚设置」分组，便于集中管理；并对各功能区做分组整理，提升配置直观性。

• 版权与备案迁移：将原「基础设置」中的 footer_text（页脚版权文字）与 icp（ICP 备案号）移动到「页脚设置」分组。
  • theme.config?.basic?.footer_text → theme.config?.footer?.footer_text
  • theme.config?.basic?.icp / theme.config.basic.icp → theme.config?.footer?.icp / theme.config.footer.icp
• 页脚导航链接分组：将 privacy_url、terms_url、links_url、about_url 整理进新增的 legal_links 子分组，每个链接配独立显示开关（privacy_enabled / terms_enabled / links_enabled / about_enabled），关闭后对应链接不渲染。
  • layout.html 的 th:with 同步改为从 legal_links 读取，开关关闭时 URL 变量置为 null。
• 浅色 / 深色模式分组：将页脚背景图、透明度、文字与图标颜色整理为 light（浅色模式）与 dark（深色模式）两个子分组，取代原先平铺的 bg_image / bg_image_dark / social_color / social_color_dark 等字段。
  • 读取路径更新：footer.bg_image → footer.light.bg_image，footer.social_color_dark → footer.dark.social_color 等，透明度同理分属 light / dark。
• 页脚订阅表单提交地址迁移：将 footer_subscribe_action 从「博主信息」(social) 分组移动到「页脚设置」分组末尾。
  • theme.config?.social?.footer_subscribe_action → theme.config?.footer?.footer_subscribe_action

页脚新增服务商 / 赞助商信息

在页脚底部新增可配置的服务商 / 赞助商信息模块（如云服务、CDN 提供商）。

• 新增「页脚设置 → 服务商/赞助商」子分组 (footer.sponsor)：
  • enabled：是否显示服务商信息（默认关闭）。
  • icon：Iconify 图标名（如 ri:cloud-line）或完整图片 URL。
  • name：服务商名称（如 腾讯云、阿里云、京东云）。
  • url：服务商链接，留空则名称显示为纯文本。
  • prefix / suffix：名称前 / 后文字，留空不渲染、不留空格。
  • name_is_link：名称是否为超链接（默认开启）。
• 渲染结构：prefix 与 suffix 在外层，icon 与 name 包在 .footer-sponsor-brand 内紧挨显示（gap:0，icon 加 margin-right:2px 微调）；仅当 enabled 且 name 非空时渲染整块。
• 新增 .footer-sponsor 系列样式，复用主题色变量与 hover 过渡，与页脚其它元素风格一致。

效果示例（配置 name=腾讯云、url=https://cloud.tencent.com、suffix=提供 CDN 加速/云存储服务）：

☁ 本网站由 腾讯云 提供 CDN 加速/云存储服务

其中「腾讯云」为指向服务商链接的超链接，图标使用主题主色调。

友情链接页面 (Links Page) 重构与优化

• 重新设计并重构友情链接页面 (links.html / links.css / links.ts)，统一卡片视觉与交互。
• 新增分类导航，支持按分组筛选；分类图标可通过注解 (theme-cosolar-linkgroup-icon) 自定义（Iconify / iconfont）。
• 新增详细 / 简洁两种视图切换，偏好通过 localStorage 记忆。
• 提交友链表单：
  • 新增「申请友链」CTA 区块开关 (links.show_apply_cta)。
  • 新增表单字段显示控制 (links.form_fields)，可隐藏 logo / 邮箱 / 描述 / 友链 / RSS 等字段。
  • 提交成功 / 失败提示优化为居中胶囊样式，并修复关闭弹窗后提示残留的问题。
  • 验证码、表单等样式在深色模式下同步适配。
• 移动端专项优化：
  • 分类导航改为下拉选择，避免网格溢出。
  • 顶部「分类 + 提交友链」整合为同一行。
  • 工具栏（搜索 / 排序 / 视图切换）整合为单行布局。
  • 卡片网格使用 minmax(0, 1fr)，消除横向滚动；卡片描述最多显示 3 行并省略。
  • 申请弹窗内验证码与图片同排，合理分配宽度。

登录页面 (Login) 样式重构与移动端适配

• 社交登录按钮重做：
  • 按 Halo OAuth2 插件真实 DOM 结构（.pill-items > li > form.social-auth-provider-form > button）编写样式，修复原规则被 .cos-card form button[type="submit"] 覆盖导致样式不生效的问题（提升选择器特异性并加 !important）。
  • 统一为中性描边胶囊按钮：白底、--c-border 边框、圆角，悬停仅文字 / 边框变主题色，不浮动、无阴影动画、不区分第三方平台品牌色。
  • 解除 .pill-items li 的边框影响，避免按钮外层出现黑框。
  • PC 端彻底移除悬停动画（transition 仅过渡颜色，transform:none、阴影锁定）。
• 登录主按钮：
  • 补充 min-height:48px 与 line-height:1，修复不同浏览器默认行高导致的高度异常。
• 移动端（≤480px）独立布局：
  • 卡片全宽撑满屏幕、无阴影、内容自然紧凑，不再强制垂直居中导致大片空白。
  • 输入框高度提升至 54px、登录按钮 52px、字号 16px，触控更友好。
  • 社交登录按钮改为自适应排布（flex-wrap，单项 min-width:140px），列数由后台配置决定，不写死。
  • 平板及以下隐藏登录页背景图，仅保留纯色背景，只显示登录表单。
• 构建产物 login-*.css 同步更新。

文档与配置

• 新增 docs/links-rest-api.md 与 docs/links-theme-api.md，说明友情链接 REST API 与主题集成能力。
• settings.yaml 新增友链相关设置项。
• annotation-setting.yaml 新增 LinkGroup 图标注解字段。

其他

• main.css 全面整理与变量统一。
• 移除废弃的 password-reset.css，相关样式并入 main.css。
• 更新 README.md 与 .gitignore。

分页组件 (Pagination) 重构

• 重新设计 src/partials/pagination.html 与 main.css 中的分页样式，使其与文章卡片视觉权重协调。
• 结构精简：移除首页 / 末页按钮，保留「上一页 / 当前页码 / 下一页」核心控件，跳转区移除「跳至 / 页」中文，仅保留输入框 + Go 按钮。
• 视觉层级：
  • 下一页：主色实心按钮（最强 CTA），hover 时背景变深 + 阴影光晕 + 图标向右滑动 2px。
  • 上一页：次级描边按钮，hover 时主色文字 + 淡背景 + 图标向左滑动 2px。
  • 当前页码：弱化文本 当前 / 总，字号 / 字重区分主次，不抢戏。
• 尺寸压缩：按钮高度统一为 28px（PC）/ 24px（移动端），圆角 6-8px，与文章卡片标签同等量级。
• 响应式：
  • PC 端：上一页 / 下一页显示「图标 + 中文」组合，最直观易认。
  • 移动端（≤640px）：自动隐藏中文文字标签，仅保留图标 + 页码，节省横向空间。
• 修复：SVG 与中文文字垂直居中对齐（SVG 设为 display:block + flex item，文字 line-height:1）。
• 修复：下一页按钮 hover / active 态文字颜色未显式声明导致与绿色背景同色「消失」的问题。

链接管理插件：较新版beta加入了友链提交功能，具体可以查看插件说明。

halo-theme-cosolar v1.1.2

新增功能

• 邮箱密码找回页面：新增 password_reset_email_send.html 与 password_reset_email_reset.html 两个官方网关片段，以及 send.html / reset.html 页面，全部中文化（标题、副标题、按钮、提示、错误文案），采用居中的单栏美化布局。
• 文章页面设置分组：在后台设置中新增独立的「文章页面（post）」分组，集中管理文章相关配置：
  • show_post_title：是否显示文章标题（默认开）。
  • toc_show_h1：右侧目录是否包含正文 H1 级标题（默认关）。
  • show_content_h1：是否渲染显示正文内手动撰写的 H1 标题（默认开），与目录 H1 开关相互独立。
  • toc_width：文章目录宽度（默认 240，范围 180–320），由原「主题样式」分组迁入。
  • default_post_cover：文章缺省封面图，由原「主题样式」分组迁入。

问题修复

• 注册页邮箱注册不正常：
  • 错误提示缺失、协议勾选校验、提交时字段 trim、与官方片段对齐等问题已修复。
  • 注册失败时顶部错误红框无文字的问题修复：增加 !#strings.isEmpty(error) 判断与兜底文案「注册失败，请检查填写内容」。
• 注册页表单挤压：优化注册表单布局，避免邮箱/验证码区域在窄屏下被挤压，并兼容移动端显示。
• 注册失败滚动问题：表单在 ≤900px 视口下由框内滚动改为页面自然滚动（height:auto / min-height:100dvh / overflow:visible），不再出现框内滚动条。
• 退出页头像占位优化：用户未设置头像时展示首字母渐变圆标占位（青绿色渐变）。
• 退出页 500 错误：修复 SpEL 表达式中混用选择表达式 *{...} 与工具表达式 #strings 导致的 TemplateProcessingException。同时修正头像判断始终走占位逻辑的问题（th:object 上下文下误用 ${spec.avatar} 读不到值），现统一使用 ${user.spec.avatar} 等完整路径，已设置头像时正确显示真实头像。
• 注册页 / 登录页移动端兼容：补充 iOS 输入防缩放（font-size:16px）、断点响应式（768 / 480 / 360 / 横屏）等适配。

其他

• 后台「主题样式（style）」分组中的 toc_width 与 default_post_cover 已迁出至新的「文章页面（post）」分组，所有代码引用同步由 style.* 改为 post.*。
• docs/使用教程.md 同步更新：目录与章节重新排序，文章页面成为独立第 17 节，并完整列出 5 个设置项说明。

升级提示

直接覆盖主题文件并重新构建（pnpm build）即可。设置项 post.* 已带默认值，旧站点的 style.toc_width / style.default_post_cover 配置将不再生效，请到「文章页面」分组重新确认。

halo-theme-cosolar v1.1.1

图标系统重构

图标库统一

• 新增图标库切换选项：支持 Iconify（默认，开箱即用）和 iconfont（阿里巴巴，自定义图标）两种模式
• 移除内置 iconfont 字体文件（src/assets/fonts/），改由用户按需自建 iconfont 项目并通过 CSS 地址引入
• 导航栏、分类、标签等内置 SVG 图标不受图标库切换影响，保持独立渲染

社交图标配置升级

• 新增 博主社交图标 数组配置，支持动态添加任意数量的社交链接
• 每个图标项独立控制显隐（显示此图标 开关），无需删除即可临时隐藏
• 统一通过图标库名称渲染（Iconify 填 mdi:github，iconfont 填 icon-github），颜色自动跟随文字色
• 移除 SVG 文件上传方式，简化为仅图标名模式
• 侧边栏博主卡片与页脚社交区域共用同一份配置，一次配置两处生效

社交链接精简

• 移除掘金、微信公众号、CSDN、知乎等独立社交字段配置
• 移除 GitHub、邮箱、RSS 独立字段，统一归入博主社交图标数组管理
• 侧边栏与页脚均移除兜底显示逻辑，未配置则显示空

样式优化

导航栏

• 修复导航栏图标与文字水平不居中问题（line-height 导致基线偏移）
• 采用 flexbox 布局 + --svg-vertical-align: 0 实现几何中心对齐

页脚社交图标

• 修复 Iconify 图标在圆形容器中偏小且不居中的问题
• 增大图标尺寸至 20px，添加 inline-flex 居中对齐

侧边栏

• 分类图标更新为书本样式 SVG
• 标签图标更新为标签点样式 SVG
• 社交图标容器恢复 32×32px、图标 22px、6px 圆角边框样式

图库改进

删除交互修复

• 修复删除照片后页面未及时刷新的问题：删除成功后立即从 DOM 移除卡片并精确更新对应计数（总数、分组数、未分组数），不再整页重拉（后端读接口存在写入传播延迟，重拉会重新渲染已删照片）
• 删除后若该页照片删空，自动显示空状态并隐藏分页器

分组导航优化

• 将「不分组」选项移至分组列表之后（顶部筛选栏与侧边栏小组件均调整）
• 未分组照片数量为 0 时，自动隐藏「不分组」选项

操作按钮权限开关

• 后台「图库页设置」新增 显示操作按钮 开关（默认开启）
• 上传、删除等图库操作按钮仅当 访客已登录且开启此开关 时才显示；关闭后所有访客（含登录用户）均看不到操作按钮

其他

• 版本号升级至 1.1.1
• 清理无用代码与冗余样式

halo-theme-cosolar v1.1.0

一、移动端导航系统重构

导航抽屉优化

• 子菜单改为手风琴折叠模式，仅展开当前选中的父级菜单
• 新增半透明毛玻璃遮罩，点击遮罩或按 ESC 键关闭菜单
• 父级菜单展开时箭头 180° 旋转，提供清晰的状态反馈
• 顶级菜单以卡片样式呈现（带边框/阴影），子菜单以缩进列表 + 引导线区分层级
• 菜单打开时锁定背景滚动（body.nav-open）
• 窗口 resize 时自动关闭菜单，避免状态残留

导航选中状态修复

• 修复外部链接（如 https://agentbook.com）导致正则匹配空路径，造成多个按钮同时高亮的问题
• 将路径匹配条件从 linkPath != "/" 改为 linkPath.length > 1，避免空字符串误匹配

二、首页移动端优化

文章列表布局（仅列表视图，卡片视图不变）

• 布局改为：标题独占一行 → 图片与（摘要、标签）并列 → 元信息行
• 摘要可显示 3 行（原为 1 行）
• 使用 CSS Grid 实现左右分栏，移动端自适应

轮播图优化

• 移动端轮播高度缩减（768px: 200px，480px: 168px）
• 新增主题设置项：移动端轮播图仅显示文章封面（默认关闭）
• 仅封面模式下，优先显示文章自带的封面图（featured.spec.cover），无封面时回退到配置封面或渐变背景

移动端隐藏区域

• 首页底部「统计信息」和「订阅更新」区块在移动端自动隐藏

三、标签页 / 分类页移动端适配

tag.html / category.html

• 为文章列表添加 .article-list 容器和 .article-card-text 包装器
• 使移动端 CSS Grid 布局正确生效（标题 → 图文并列 → 元信息）

四、资讯页（feeds.html）移动端适配

Hero 区域

• 精简内边距和字号
• 统计栏改为横向滚动，防止小屏溢出

频道导航重构

• 移动端隐藏「我的频道」标题和「管理订阅源」按钮
• 频道标签改为单行横向滚动，胶囊样式，隐藏数字计数
• 防溢出修复：.feed-sidebar--left 加 min-width: 0; overflow: hidden
• .feed-layout 在 1024px 断点加 min-width: 0

资讯列表

• 紧凑卡片布局，来源与时间合并一行
• 标题 + 摘要精简显示

五、友链页（links.html）移动端适配

Hero 区域

• 768px 断点隐藏第三个装饰性统计项「∞ 无限可能」
• 统计栏改为横向滚动，适配小屏

筛选 + 搜索工具栏

• 筛选标签改为单行横向滚动，移动端隐藏标签内数字计数
• 搜索框从工具栏拆出，独立全宽一行
• 防溢出修复：.links-toolbar 加 min-width: 0; overflow: hidden

友链卡片

• 移动端单列布局，紧凑间距
• Logo 缩小至 36px（480px: 32px），描述限制 1 行
• CTA 区域在 480px 隐藏装饰元素

六、全局防溢出修复

• html 元素添加 overflow-x: hidden，作为防止横向滚动的安全网
• 所有 CSS Grid 子项在移动端断点添加 min-width: 0，确保 overflow-x: auto 正确生效

升级须知

1. 在 Halo 后台卸载当前主题
2. 上传 halo-theme-cosolar.zip 并重新安装
3. 清除 Thymeleaf 模板缓存（ crucial — 否则模板变更不生效）
4. 如需启用「移动端轮播图仅显示封面」，前往 主题设置 → 首页轮播 开启

halo-theme-cosolar v1.0.10

新增

• 移动端轮播图仅显示封面：在「首页轮播」设置中新增 mobile_carousel_cover_only 开关（默认关闭）。启用后，移动端（≤768px）轮播图将隐藏标题、摘要、标签、按钮等文字内容，只展示封面图片；并优先使用文章自带的封面图，未设置时回退到主题配置封面或默认背景。全卡片可点击跳转对应文章。

优化

• 移动端导航重构：子菜单改为手风琴折叠式，修复动画错位、无法展开子菜单、箭头无旋转等问题。新增毛玻璃遮罩层、背景滚动锁定、ESC 关闭、遮罩点击关闭、窗口缩放自动关闭、当前页子菜单自动展开等交互。顶层菜单为卡片样式，子菜单为缩进列表，层级更清晰。
• 移动端文章列表布局：列表视图改为「标题占一行 → 图片与（摘要、标签）并列 → 元信息在底部」的网格布局，摘要支持显示 3 行。卡片视图保持不变。
• 移动端轮播图精简：降低高度、内容全宽、简化信息、优化控件尺寸。
• 移动端隐藏次要模块：自动隐藏统计信息和订阅更新区域，减少移动端信息过载。

修复

• 导航栏多选 BUG：修复外部链接菜单项被错误标记为激活状态的问题。原因是外部链接去除协议和域名后 linkPath 变为空字符串，导致 currentPath.startsWith("") 永远返回 true。现已通过 linkPath.length > 1 条件排除空串和单字符路径的误匹配。

升级方法

1. 后台「主题管理」卸载当前版本
2. 上传 halo-theme-cosolar.zip 安装新版本
3. 重新激活主题（清除 Thymeleaf 模板缓存）
4. 如需启用移动端仅封面轮播：进入「首页轮播」设置，打开「移动端轮播图仅显示封面」开关

halo-theme-cosolar v1.0.9

新增功能

📸 图库(Photos)页面

• 新增独立图库页 photos.html / photo.html,支持分组展示与灯箱查看。
• 灯箱支持鼠标滚轮放大/缩小(0.5×–5×)及放大后拖拽查看;触摸屏支持双指捏合与滑动切换。

💬 瞬间(Moments)页面

• 新增瞬间流页面 moments.html / moment.html。
• 图片灯箱同样支持滚轮缩放、拖拽与滑动切换。
• 点赞 / 分享功能:点赞调用 Halo tracker 接口,分享支持系统分享面板与原生复制链接。

halo-theme-cosolar v1.0.8

更新内容

• 修复导航栏多级菜单显示问题；
• 修改用户下拉选项显示看不清；

---

主题仓库：https://github.com/cosolar/halo-theme-cosolar
问题反馈：https://github.com/cosolar/halo-theme-cosolar/issues

halo-theme-cosolar v1.0.7

发布日期：2026-07-19

概述

本次更新聚焦页脚区域的重构与功能增强，新增首页滚动加载模式，完善用户菜单，并提供了全新的主题配置手册。

---

新功能

🔥 页脚全面重构

• 页脚主区域显隐开关：可通过后台设置 显示页脚主区域 控制品牌、统计与订阅区域的显示/隐藏，底部版权信息始终保留
• 品牌区：可独立配置页脚 Logo（图片/文字）、名称、标语、站点简介，支持自定义 Logo 尺寸
• 网站统计面板：实时展示访问量、点赞数、评论数、文章数、分类数、标签数，以及建站时间和博主所在地
• 订阅表单：内置邮件订阅表单，支持对接第三方邮件订阅服务（如 Mailchimp），未配置时显示"功能待开发"提示气泡
• 法律信息链接：支持配置隐私政策、使用条款、友情链接、关于我们四个导航链接，带图标分隔展示
• 社交图标升级：社交链接展示为纯图标按钮（移除文字标签），新增微信公众号、RSS 订阅图标，交互更简洁美观
• 背景图增强：支持页脚背景图片，亮色/深色模式分别配置，独立控制透明度，防止干扰内容阅读
• 文字颜色自定义：亮色/深色模式可分别设置页脚文字与图标颜色，适配不同背景图

📜 首页滚动加载模式

• 新增「首页加载方式」配置项，支持 分页（默认）和 滚动加载 两种模式
• 滚动加载模式下，滚动到底部自动加载下一页文章（IntersectionObserver 实现，提前 400px 预加载）
• 同时保留「查看更多文章」按钮作为兜底，保证无 JavaScript 场景可用
• 客户端无刷新加载，轮播图在加载过程中始终保留，体验更流畅

🧭 用户菜单扩展

• 用户下拉菜单新增「发布文章」入口，直接跳转编辑器
• 新增「个人中心」入口，跳转至用户中心页面

⚙️ 设置项新增

• 博主信息区新增 博主所在地、个人网站、建站时间 字段
• 社交链接新增 微信公众号 字段
• 页脚设置新增完整的配置表单（Logo、背景图、透明度、颜色、法律链接等 20+ 项）

---

修复

• 修复页脚背景图 SpEL 模板中引号转义错误，确保背景图在页脚正常渲染
• 修复「显示页脚博主信息」开关重构后不再生效的问题（已迁移至新的页脚主区域开关）

---

文档

• 新增 主题配置手册，完整覆盖所有后台配置项，含截图说明与配置建议
• 精简 README 使用教程章节，降低新用户上手门槛

---

技术细节

• 版本：1.0.7（theme.yaml）
• 兼容性：要求 Halo >= 2.20.0
• 依赖：plugin-links（友情链接）、plugin-search-widget（搜索挂件）等
• CSS 变更：页脚样式全面重写，新增 900+ 行 CSS，支持毛玻璃效果、统计网格、响应式布局
• JS 变更：新增客户端翻页/滚动加载模块（index.ts），页脚订阅提示气泡（main.ts）
• 模板变更：layout.html 页脚部分重写，pagination.html 翻页组件重构，index.html 首页加载逻辑拆分

---

升级说明

1. 更新主题文件后，请进入后台 → 主题 → 设置，重新保存页脚相关配置以生效
2. 如使用自定义 CSS/JS 覆盖了页脚样式，请检查兼容性
3. 新增的「首页加载方式」默认为分页，如需体验滚动加载，请在主题设置中切换

halo-theme-cosolar v1.0.6

✨ 新增

• 用户菜单与登录态体验优化
• 用户菜单下拉框：登录后鼠标悬停用户图标，弹出毛玻璃风格的下拉菜单。
  • 显示当前用户昵称
  • 「控制台」入口（带齿轮图标，跳转 /console）
  • 「退出登录」入口（带退出图标，跳转 /logout）

🐛 修复

• 修复用户下拉菜单不显示的问题：普通主题模板中登录态判断原使用了错误的变量，现改用 Halo 标准的 #authentication + contributorFinder.getContributor(...) 方式正确获取当前用户，下拉框可正常渲染。
• 修改1.0.5产生的BUG

💄 优化

• 登录态用户图标仅显示主题色，移除背景填充，更简洁。
• 下拉框升级为毛玻璃（磨砂）效果：backdrop-filter 模糊 + 半透明背景与边框，浮层更有层次。
• 菜单项悬停态细化：浅主题色背景 + 轻微位移，新增分隔线与退出项的危险色区分。

⚙️ 注意

• 需要安装 plugin-links 链接管理插件，用于管理友情链接、检查链接状态，并将链接站点的 RSS / Atom 动态聚合到 Halo Console 中。
• 开启RSS功能

halo-theme-cosolar v1.0.5

本次更新大幅扩展了主题的交互页面能力，新增登录/注册/登出、友情链接、RSS 资讯三大模块，并对侧边栏配置与模板健壮性做了增强。

✨ 新增功能

1. 登录 / 注册 / 登出页面（全新网关页）

• 青绿美学的左右分栏布局：左侧品牌展示区（Logo、标语、动态装饰），右侧表单卡片。
• 支持本地账号登录、其他登录方式（formAuthProviders）、社交登录，含「记住我」「忘记密码」入口。
• 新增注册页与退出确认页，复用同一套分栏布局与样式。
• 登录页专属设置项（设置 → 登录页面）：
  • 左侧品牌区占比（20–60%）
  • 遮罩层开关、遮罩渐变主色与透明度（明暗双模各自可配）
• 主题色防闪烁脚本，避免明暗切换时白屏闪烁。
• 新增资源：src/login.html、signup.html、logout.html、login_local.html、gateway_fragments/{login,logout,signup}.html、src/css/login.css、public/assets/images/login_default.png。

2. 友情链接页面（全新页面）

• Hero 双栏 + 友链/分组/无限可能统计栏。
• 分组筛选 + 实时搜索（前端筛选，不整页跳转）。
• 友链卡片展示 Logo、在线/离线/检测中、已回链/未回链 徽章。
• 「申请友链」CTA（mailto）、底部评论组件。
• 配套交互脚本：src/js/links.ts。

3. RSS 资讯页面（全新自定义页面模板）

• 三栏布局：左频道导航、中资讯流、右统计面板（资讯概览 / 活跃频道 / 抓取状态）。
• 支持按订阅源/分组筛选、分页「加载更多」。
• 依赖友情链接插件的 RSS 功能，未启用时给出友好引导提示。
• 已在 theme.yaml 注册为自定义页面模板 feeds，后台可选「RSS 资讯」页面类型。
• 配套脚本：src/js/feeds.ts。

🔧 侧边栏配置增强

• 友情链接、订阅资讯模块新增展示数量设置项（sidebar_links_count / sidebar_feeds_count）。
• 侧边栏模块顺序改为 array 列表配置，后台可拖拽排序、删除隐藏、添加恢复，取代原先逐个填写数字的方式。

🐛 模板健壮性修复

• layout.html / categories.html / category.html / post-card.html 等多处将 ${x} 判空改为 ${x != null and !#strings.isEmpty(x)}，避免空字符串误渲染。
• Logo 尺寸配置支持独立宽高。
• favicon 增加空值判断。

🎨 样式

• 主要涵盖登录页、友链页、资讯页样式及整体视觉优化。

halo-theme-cosolar v1.0.3

✨ 新功能

文章缺省封面图：

• 新增 default_post_cover 配置项，文章未设置封面时自动显示默认图片
• 内置 default_post_cover.png 作为兜底，也可在后台自定义上传

🔧 优化

• 字体设置、图标设置移入「主题样式」分组，设置项更集中
• 分组名称调整：样式设置 > 主题样式，精选文章 > 精选轮播
• 重写 README，分步骤讲解每一组配置的使用场景

🐛 修复

• 修复文章详情页默认封面图不显示的问题（th:if 与 th:with 优先级问题）
• 修复 @{...} 嵌套在 ${...} 内导致的 SpEL 解析错误
• 修复博主名字右上角创作者角标的显示逻辑

halo-theme-cosolar v1.0.2

✨ 新功能

侧边栏新增模块：

• 公告栏 — 在博主信息下方展示公告内容，支持 HTML 富文本，可插入链接和图片
• 热门标签（词云） — 替代旧列表模式，标签字体大小随文章数自动变化，带浮动起伏动画和悬停放大效果
• 公众号二维码 — 在侧边栏展示微信公众号二维码图片，可自定义图片和下方文字

博主信息卡片增强：

• 背景图模式下，遮罩层颜色和透明度现可在后台独立配置
• 博主栏文字颜色可自定义（浅色/深色模式分别配置）
• 深色模式遮罩默认透明度提升至 0.45，阅读体验更佳

社交图标更新：

• 掘金、CSDN、知乎图标更新为官方新版 logo，更清晰现代

🐛 修复

• 修复博主名字右上角创作者角标的显示逻辑

📖 文档

• 重写 README，分步骤讲解每一组配置的使用场景
• 侧边栏各模块说明同步更新

---

⚡ 升级提醒

升级后建议进入 主题设置 > 侧边栏设置，查看新增的公告栏、标签云和公众号二维码配置项，默认均为关闭状态，按需开启即可。

halo-theme-cosolar 是一款为 Halo 2.20+ 打造的现代博客主题，专为技术写作者设计。它把"内容"放回舞台中央 —— 干净的排版、克制的动效、合理的留白，让代码与文字都能舒适呼吸。同时在小屏与移动端做了完整自适应：贴底毛玻璃操作栏、抽屉式目录、自动隐藏的侧边栏，让手机阅读体验与桌面端同样顺滑。

设计亮点

• 🎨 青绿美学 — 默认主色 #10B981，可在后台一键换色，全站按钮 / 链接 / 标签 / 进度条联动
• 🌗 暗色模式 — 跟随系统 / 强制浅色 / 强制暗色三档可切，导航与操作栏毛玻璃风格
• 🖼️ 精选轮播 — 首页顶部卡片轮播，支持手动指定、自动播放、置顶回退
• 🗂️ 分类导航 + 热门标签 + 近期更新 — 侧边栏模块化组件，可单独开关
• 📚 文章目录（TOC） — 桌面端右侧悬浮跟随，移动端抽屉式弹出，1px 极细滚动条
• 📊 阅读进度条 — 顶部 2px 彩色渐变，实时反映阅读位置
• 🖱️ 图片查看器 — 文章图片点击放大，支持滚轮缩放 / 拖动 / 双击复位 / ESC 关闭，零依赖
• 👍 点赞 / 评论 / 分享 / 回顶 — 文章页底部贴底毛玻璃横条，5 按钮平分宽度
• 📱 移动端自适应 — ≤768px 侧边栏自动隐藏，导航汉堡菜单展开，操作栏贴底
• ⚡ Vite 构建 — TypeScript + vite-plugin-halo-theme，产物精简，按模板分块