Files

T

nxxy335 a08782a959 fix: 修复记得页 500 与留言板裁切，统一页头，完善友链/瞬间/暗色/排版 (v1.1.12)

记得（/important-dates）
- 修复 500：th:classappend 里 BEM 类名 wi-id__car 的两个 __ 触发 Thymeleaf
  __...__ 预处理，提取片段含引号导致 Could not parse as expression；
  皮肤修饰类改为 wi-id-skin-cool/cute/neutral（表达式内不再出现 __）
- 牵挂的人卡片：倒计时改到右上角与日期卡片一致，生日一行显示不再折行；
  网格改为桌面三列 / 平板两列 / 手机一列
- 页头与订阅/记得统一（标题-副标题-强调线间距）

友链（/links）
- 再次消除两处 __ 预处理隐患：回执修饰类改 wi-links-check-ok/error，
  验证码 onerror 由 th:onerror="|...|" 改为普通静态属性（不参与表达式解析）
- 新增反链/可达性检测徽章：读取 link.status.verification，头像右下角
  绿点=访问正常（反链有效），红点=访问异常或未检测到反链，未检测不显示

留言板
- 移除 -124px 负 margin 补偿（头部卡片顶部被导航盖住的根因），
  装饰引号 top 改为正值不再被 overflow 裁掉

瞬间
- 修复九宫格失效根因：lightgallery 处理时把每张图包进 <a>，导致
  :has(:only-child) 恒真、全部图片退化为单列大图；改为直接把 img
  作为图库项（data-src），瀑布流样式同样补上 4 图 2x2 规则

全局
- 暗色模式配色调为偏中性暖灰（bg #1e1c1a / raised #292623），降低黄褐闷感，
  同步 theme-color 与依赖旧色值的变量
- 正文排版：p 字号 1.05~1.15rem、行高 1.85，H1~H6 逐级放大、层级更清晰

新增「文章组件」插件适配
- 新增 src/styles/_widgets.scss，将插件 --xhhao-com-* 变量映射到主题变量，
  明暗模式自动跟随

2026-09-27 10:09:28 +08:00

8.4 KiB

Raw Blame History

WarmIsland 暖屿

暖如灯火，静如留白。暖屿以柔和的色调和舒缓的节奏回归内容本身，为记录与阅读留出一方安静从容的角落。

本项目由 AI 开发完成，人工仅进行部分功能测试及问题找寻

环境要求

Halo 2.26.0 及以上（页面布局契约、微信读书页面均依赖 2.26 的新能力）

特点

响应式设计 — 适配桌面端与移动端，支持暗色模式，移动端使用动态视口单位适配地址栏
插件兼容性 — 适配 11 款常用 Halo 插件，安装即用；提供页面布局契约，插件前台页面自动复用主题外观
内置灯箱 — 主题内置 LightGallery 灯箱，支持 EXIF 信息展示；安装 lightgallery.js 插件后自动禁用
可配置性 — 17 个设置分组、122 个配置项，几乎所有模块可独立开关
性能优化 — 服务端字数统计（API 扩展包）、图片懒加载与响应式缩略图、滚动吸附、CSS/HTML 压缩
页面布局契约 — 提供 templates/layout.html，插件页面不再回退到 Halo 内置布局

预览

已适配插件

插件名称	插件标识	适配页面路由	说明
瞬间	`PluginMoments`	`/moments`	瞬间动态页面，支持点赞、评论、标签筛选、顶部封面
图库	`PluginPhotos`	`/photos`	图片展示页面，支持分组、灯箱预览
友情链接	`PluginLinks`	`/links`	友链展示页面，支持随机排列、随机传送门、评论区开关
朋友圈	`plugin-friends`	`/friends`	RSS 订阅朋友圈页面
装备管理	`equipment`	`/equipments`	装备展示页面，按分组展示，支持封面图
豆瓣	`plugin-douban`	`/douban`	豆瓣记录页面，支持类型/状态/标签筛选，默认电影
Steam 信息展示	`PluginSteam`	`/steam`	Steam 游戏库页面，含用户资料、统计数据、最近游玩、游戏库分页
微信读书	`halo-weread-plugin`	自定义页面	书架展示页面，见下方「自定义页面模板」
记得	`plugin-important-dates`	`/important-dates`	重要日期 / 牵挂的人 / 爱车双视图页面，见下方「扩展页面」
文章组件	`plugin-content-widgets`	文章内	提示框、标签页、时间线等内容组件，主题已映射 `--xhhao-com-*` 变量，自动跟随明暗模式
API 扩展包	`extra-api`	全站	服务端字数统计、中英文混排排版、可选服务端代码高亮

注意：插件需要单独安装，安装后主题会自动适配对应页面。若未安装某插件，对应页面或功能自动隐藏/降级，不会报错。

自定义页面模板

在 Halo 后台「页面 → 新建 → 自定义模板」中选择使用：

模板名	模板文件	说明
留言板	`page_messageboard.html`	留言墙页面，标题与副标题可配置
订阅	`page_subscriptions.html`	博友文章订阅动态，依赖链接管理插件的 RSS 订阅，支持分页/下滑加载与列表/网格布局
微信读书	`weread.html`	微信读书书架展示，依赖微信读书插件，访客免登录查看

主要功能

首页

Hero 首屏：明暗双背景图、大标题/副标题独立配色、一言（支持自动刷新与淡入淡出过渡）、下滑箭头平滑滚动
欢迎弹窗：基于访客 IP 地理定位的欢迎提示，支持 5 种位置、自定义 API 与会话去重开关
滚动吸附：首屏与内容区之间滚轮/触摸自动吸附
文章卡片：可配置显示字数（依赖 API 扩展包）、阅读量、分类、标签、摘要行数

文章

目录（TOC）：桌面端侧栏 + 移动端抽屉，滚动高亮、展开模式可选
上下篇导航：悬停反馈与方向箭头动画
相关推荐、分享按钮、赞赏、版权声明可独立开关
字数与阅读时间：优先使用 API 扩展包的服务端统计，未安装时前端计算兜底

全局

点击特效：核心价值观 / 爱心 / 烟花 / 粒子等 9 种可选
页脚全站统计：文章、分类、评论、访问、点赞、总字数，支持开关与统计项选择（默认开启）
动效：呼吸动画、滚动渐入，可独立关闭
备案信息：ICP 与公网安备号，公网安备自动带徽标
鼠标光感跟随已移除（性能考量）

灯箱集成

主题内置 LightGallery 灯箱，为图片提供放大预览功能，并支持 EXIF 信息展示。

lightgallery.js 插件兼容

如安装 lightgallery.js 灯箱插件，主题内置灯箱将自动禁用，改由插件接管灯箱功能。以下为 lightgallery.js 插件的路径匹配规则和 DOM 节点选择器：

页面	路径匹配规则	匹配区域 DOM 节点
文章详情页	`/archives/*`	`.wi-post__body`
瞬间页	`/moments`	`.wi-moments-page__content`
图库页	`/photos`	`.wi-photos-page__grid`
自定义页面	用户自定义	`.wi-page__body`

注意：自定义页面的路径匹配由用户自行设定，此处仅提供 DOM 节点选择器 .wi-page__body。

安装

下载主题最新 Release 的 ZIP 包
进入 Halo 后台 → 主题管理 → 安装主题 → 上传 ZIP 包
安装完成后点击「启用」

或从源码构建：

git clone https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland.git
cd halo-theme-WarmIsland
pnpm install
pnpm build

构建产物在 templates/ 目录下，同时会生成 dist/ 内的安装包。

开发

# 安装依赖
pnpm install

# 开发模式（监听文件变化，自动构建到 templates/）
pnpm dev

# 构建
pnpm build

目录结构

├── src/
│   ├── components/    # 组件（导航、页脚、Hero、弹窗、特效等）
│   ├── layouts/       # Layout.astro（含页面布局契约渲染模式）
│   ├── pages/         # 页面模板（构建后输出到 templates/）
│   └── styles/        # SCSS 样式（正文样式在 _content.scss，全局生效）
├── templates/         # 构建产物，Halo 实际加载的模板
├── settings.yaml      # 后台设置项定义（16 分组 / 117 项）
└── theme.yaml         # 主题清单与自定义页面模板注册

主题开发注意事项

Thymeleaf 字符串字面量必须加单引号：th:text="'文本'"，裸中文遇到逗号/空格/emoji 会导致页面 500
正文样式必须写在全局样式表（src/styles/_content.scss）：Astro scoped 样式对 Thymeleaf 运行时注入的内容无效
内联脚本统一加 th:inline="none"：避免 Thymeleaf 解析脚本中的 [[ / [( / ${}
修改主题外观无需单独维护 layout.astro：页面布局契约复用 Layout.astro，构建时自动生成

技术栈

Halo 2.26+
Astro + vite-plugin-halo-theme
Thymeleaf 模板引擎
Sass 样式

许可

GPL-3.0

图标来源

本主题使用的图标来自以下开源项目：

来源	协议	用途
Font Awesome Free v7.2.0	CC BY 4.0 / SIL OFL 1.1	QQ 分享图标
Simple Icons	CC0 1.0	微博、X、Facebook、Telegram 分享图标
Feather Icons	MIT	导航、界面交互图标
Halo	GPL-3.0	主题内置图标

8.4 KiB Raw Blame History Unescape Escape