✨ 为什么选择 halo-theme-cosolar？

把「内容」放回舞台中央 —— 干净的排版、克制的动效、合理的留白，让代码与文字都能舒适呼吸。

市面上 Halo 主题很多，但专为技术写作者量身打造的却很少。halo-theme-cosolar 从开发者的真实阅读场景出发，打磨了每一个交互细节：

🎯 功能全览

🎨 视觉与主题

• 青绿美学 — 默认主色 #10B981，后台一键换色，全站联动
• 暗色模式 — 跟随系统 / 强制浅色 / 强制暗色三档可切
• 毛玻璃风格 — 导航栏与操作栏 backdrop-filter 毛玻璃质感
• 页面背景 — 支持自定义背景图（浅色/深色分别配置）和 5 种动态渲染背景

🖼️ 首页体验

• 精选轮播 — 首页顶部卡片轮播，手动指定文章、自动播放、置顶回退
• 文章卡片 — 封面图 + 标题 + 摘要 + 分类标签 + 时间，信息密度恰到好处
• 侧边栏 — 博主信息 / 热门标签 / 分类导航 / 近期更新，模块化可单独开关

📖 阅读体验

• 文章目录（TOC） — 桌面端右侧悬浮跟随，移动端抽屉式弹出，1px 极细滚动条
• 阅读进度条 — 顶部 2px 彩色渐变，实时反映阅读位置
• 图片查看器 — 点击放大，滚轮缩放 / 拖动 / 双击复位 / ESC 关闭，零依赖
• 点赞 / 评论 / 分享 / 回顶 — 文章页底部贴底毛玻璃横条，5 按钮平分宽度

📱 移动端适配

• ≤768px — 侧边栏自动隐藏，导航收起为汉堡菜单，操作栏贴底
• ≤480px — 小屏进一步紧凑，按钮间距收窄
• 769–1024px — 平板隐藏 TOC 列，保留内容 + 侧边栏双栏

🔧 个性化

• 自定义字体 — 支持引入第三方字体 CSS，一键切换全局字体
• 自定义图标 — 支持 Remix Icon、Font Awesome 等第三方图标库
• 自定义背景 — 背景图浅色/深色分别配置，5 种 Canvas 动态背景可选
• 封面图配置 — 分类页、标签页、归档页 Hero 区域均可自定义封面图

📸 预览

🚀 演示站点： https://note.minims.cn

🚀 安装与启用

环境要求

方式一：直接安装（推荐）

1. 前往 Releases 下载最新 cosolar-<version>.zip
2. 登录 Halo 后台，进入 主题管理 → 安装主题 → 上传 ZIP
3. 安装完成后点击 启用 🎉

方式二：从源码构建

适用于需要二次开发或自定义修改的场景。

git clone https://github.com/cosolar/halo-theme-cosolar.git
cd halo-theme-cosolar
pnpm install
pnpm build            # 产物：templates/ + cosolar-<version>.zip

将生成的 ZIP 上传到 Halo，或将整个目录放入 Halo 工作目录的 themes/cosolar/ 下。

📖 使用教程

主题启用后，进入 Halo 后台 → 主题管理 → halo-theme-cosolar → 设置 进行配置。以下按使用场景分步讲解。

1️⃣ 基础配置：让你的博客「像你的」

打开 基础设置 分组，配置站点身份信息：

2️⃣ 视觉风格：打造专属配色

打开 样式设置 分组：

换一个主题色：点击「主题色」颜色选择器，选一个你喜欢的颜色。全站的按钮、链接、标签、进度条、选中态等都会联动变化。推荐色值参考：

配色方案：选择默认的明暗模式：

• 跟随系统 — 根据用户操作系统的深浅色设置自动切换
• 浅色 / 暗色 — 强制使用指定模式，用户仍可通过导航栏月亮/太阳按钮手动切换

布局微调：根据你的内容类型调整宽度参数：

• 内容最大宽度：文字类博客建议 1100–1200，图片类可加大到 1400
• 侧边栏宽度：默认 320px，内容多可调到 360
• 内容间距：内容区与侧边栏之间的间距，默认 24px

3️⃣ 字体与图标：个性化排版

切换全局字体

打开 字体设置 分组。默认使用霞鹜文楷（中文）+ JetBrains Mono（代码），如果你想换字体：

示例：切换为思源黑体

1. 在「字体 CSS 地址」填入：https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;700&display=swap
2. 在「正文字体族」填入："Noto Sans SC", sans-serif
3. 保存即可生效

💡 留空任何字段都会使用默认值，不需要全部填写。

常用中文字体 CSS 地址：

💡 如需完全离线部署，可自行下载字体文件并上传到 Halo 附件管理，然后在「字体 CSS 地址」填入本地路径。

切换图标库

打开 图标设置 分组。默认使用内置 iconfont 图标，如需更丰富的图标：

示例：切换为 Remix Icon

1. 在「图标字体 CSS 地址」填入：https://cdn.jsdelivr.net/npm/remixicon@4.6.0/fonts/remixicon.css
2. 在「图标类名前缀」填入：ri
3. 在 菜单管理 中，给菜单项添加注解 icon，值为 Remix Icon 图标类名（如 ri-home-line、ri-article-line）

常用图标库：

4️⃣ 页面背景：让博客更有氛围

背景设置分为 浅色模式 和 深色模式 两个独立分组，可以分别配置不同效果，切换主题时自动切换对应背景。

浅色模式背景

打开 页面背景 · 浅色模式 分组，支持三种类型：

• 无（默认纯色） — 使用浅色背景色 #F8FAFC
• 自定义背景图 — 上传一张浅色调背景图，调整透明度（建议 0.1–0.3）
• 动态渲染背景 — 选择动态效果类型，自定义颜色和透明度

深色模式背景

打开 页面背景 · 深色模式 分组，配置方式与浅色模式相同：

• 无（默认纯色） — 使用深色背景色 #0F172A
• 自定义背景图 — 上传一张深色调背景图，调整透明度
• 动态渲染背景 — 默认推荐「星空闪烁」，与深色背景更搭配

动态背景效果

浅色和深色模式均可独立选择以下 5 种动态效果：

每种动态效果都可以自定义主色、辅色和透明度，透明度建议 0.05–0.3。

💡 两种模式的背景完全独立：浅色模式可以用粒子连线，深色模式用星空闪烁，互不影响。切换主题时背景平滑淡入淡出。

5️⃣ 首页精选轮播：展示你的最佳内容

打开 精选文章 分组：

手动指定模式（推荐）：

1. 开启「启用精选文章」
2. 在「精选文章列表」中点击添加，选择要展示的文章
3. 可拖拽排序，最上面的文章显示在第一张
4. 开启「自动轮播」并设置间隔时间（默认 5 秒）

自动回退模式：
如果未指定精选文章，主题会根据「无配置时的回退策略」自动处理：

• 显示最新文章 — 自动选取最新发布的 N 篇文章
• 显示置顶文章 — 自动选取置顶文章
• 不显示 — 不展示轮播区域

封面图逻辑：

• 默认开启「优先使用文章封面」— 如果文章本身有封面图则使用，否则使用「轮播默认背景图」
• 如果两者都没有，使用主题自带的渐变背景

6️⃣ 侧边栏：按需展示信息

打开 侧边栏设置 分组：

博主信息卡片：

• 开启「显示博主展示」后，侧边栏顶部会显示博主头像、昵称、简介、文章/分类/标签统计和社交链接
• 可设置博主背景图或背景色（二选一，背景图优先），让卡片更有视觉冲击力
• 社交链接支持 GitHub、邮箱、掘金、RSS

其他模块：每个模块都可独立开关：

• 热门标签 — 显示最热门的 N 个标签，可配置数量
• 分类导航 — 显示分类列表，可配置数量
• 近期更新 — 显示最新发布的 N 篇文章

7️⃣ 分类与标签页：自定义封面

分类页设置

打开 分类页设置 分组：

• 分类列表页封面图 — 分类汇总页顶部 Hero 区域的背景图
• 分类详情页封面图 — 进入某个分类后的页面顶部背景图
• 开启「优先使用分类自带封面」— 如果你在 Halo 后台给分类设置了封面图，会优先使用

标签页设置

打开 标签页设置 分组：

• 标签列表页封面图 — 标签汇总页顶部 Hero 区域的背景图
• 标签详情页封面图 — 进入某个标签后的页面顶部背景图
• 如果标签本身设置了封面图，会优先使用

归档页设置

打开 归档页设置 分组：

• 归档页封面图 — 归档页顶部 Hero 区域的背景图

💡 所有封面图留空时，都会显示主题默认的青绿渐变动画背景，效果同样出色。

8️⃣ 社交与页脚：展示你的身份

打开 社交链接 分组：

• 显示页脚博主信息 — 控制页脚博主卡片的显示/隐藏
• 填写博主昵称、头像、简介 — 留空则使用站点标题和默认头像
• 配置社交链接 — GitHub、邮箱、掘金、RSS（RSS 留空则使用默认地址）

页脚底部还会显示版权文字和 Powered by Halo · Theme Cosolar 信息。

9️⃣ 导航菜单：配置图标与链接

1. 进入 Halo 后台 → 菜单管理，创建或编辑菜单
2. 添加菜单项，填写名称和链接
3. 如需显示图标，在菜单项的 注解 中添加 icon 字段，值为图标类名

内置 iconfont 图标类名参考：

💡 如果切换了第三方图标库（如 Remix Icon），则使用对应图标库的类名（如 ri-home-line）。

🔟 搜索功能

主题已适配 Halo 官方搜索插件：

1. 在 Halo 后台安装 PluginSearchWidget 插件
2. 导航栏会自动显示搜索框，支持 Ctrl+K 快捷键
3. 如果未安装搜索插件，搜索框会降级为归档页链接

❓ 常见问题

如何关闭模板缓存以便开发调试？

• Docker 部署：添加环境变量 SPRING_THYMELEAF_CACHE=false
• 源码部署：在 application.yaml 中设置 spring.thymeleaf.cache: false

代码高亮如何配置？

代码高亮由 Halo 的 plugin-shiki 插件负责，在 Halo 后台 → 插件管理 → Shiki → 设置 中配置亮色/暗色主题，主题本身不再提供代码高亮选项。

如何完全离线部署？

1. 下载 lxgw-wenkai-screen-webfont 字体文件
2. 上传到 Halo 附件管理
3. 在 字体设置 中将「字体 CSS 地址」替换为上传后的本地路径
4. 图标字体已内置在主题中，无需额外处理

动态背景会影响性能吗？

动态背景使用 Canvas 2D 渲染，粒子数量会根据屏幕尺寸自动调整（最多 80 个粒子 / 150 颗星星），对现代设备几乎无性能影响。如仍有顾虑，可降低透明度或切换为静态背景图。

如何让文章出现在精选轮播中？

两种方式：

1. 手动指定：在「精选文章」设置中直接选择文章
2. 自动回退：将文章设为置顶，然后选择回退策略为「显示置顶文章」

博主信息卡片的背景图和背景色有什么区别？

• 背景图：适合使用深色图片，文字会自动变为白色，并添加半透明遮罩确保可读性
• 背景色：适合使用纯色或渐变色，效果更简洁
• 两者同时设置时，背景图优先

🛠️ 开发

pnpm install
pnpm dev              # 监听文件变化，实时构建到 templates/
pnpm check            # 检查模板与配置
pnpm build-only       # 仅构建（不打 ZIP），用于本地联调
pnpm build            # 完整构建 + 打 ZIP 包

📐 响应式断点

🗺️ 路线图

• i18n 多语言（中 / 英）
• 搜索结果页模板
• 404 / 500 错误页美化
• 文章系列/专栏支持
• 首页布局模式切换（列表 / 瀑布流）

🤝 贡献

欢迎提 Issue 与 PR！无论是 Bug 反馈、功能建议还是代码贡献，都让 halo-theme-cosolar 变得更好。

1. Fork 本仓库
2. 新建分支：git checkout -b feat/your-feature
3. 提交：git commit -m "feat: ..."（遵循 Conventional Commits）
4. 推送并提交 Pull Request

🔒 第三方服务资源

本主题在页面加载时可能请求以下第三方资源：

说明：

• 默认配置下，iconfont 图标字体已完全本地化，霞鹜文楷字体通过 elemecdn 公共 CDN 按需加载
• 如需完全离线部署，可在后台 字体设置 中将字体 CSS 地址替换为本地路径
• 如配置了第三方图标库（如 Font Awesome、Remix Icon），浏览器将向对应 CDN 请求资源

📄 许可证

GPL-3.0

💝 致谢

• Halo — 强大易用的开源建站平台
• 所有为本主题提过 Issue 与建议的用户

如果 halo-theme-cosolar 对你有帮助，给个 ⭐ Star 吧！