nxxy335/halo-theme-WarmIsland
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

feat(v1.2.7): 全面校准文档并精简三个可选 API 配置项文案

Browse Source 
- 文档对齐 1.2.7：feed/RSS 聚合改由官方链接管理插件订阅承担、Halo 要求统一 >=2.27.0、补齐设置分组文档、清理与代码不符的描述，并修复正文引用块留白
- 三个可选 API 设置项 help 只保留功能说明，隐私披露统一由 README「外部资源与隐私」与文档站承载；字段恢复按开关条件显示，修正配置块缩进
- audit:external 改为防回潮检查：字段存在、help 不得出现披露文案、README 必须保留隐私披露章节
This commit is contained in:
nxxy335 committed 2026-11-11 22:34:32 +08:00
1 parent c92429d139
commit 5c7c6325b1
34 files changed
+500 -210
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/.vitepress/config.mts
+4 -2
View File
@@ -35,7 +35,9 @@ export default defineConfig({
{ text: '瞬间', link: '/config/moments' },
{ text: '图库', link: '/config/photos' },
{ text: '友情链接', link: '/config/links' },
{ text: '朋友圈', link: '/config/friends' },
{ text: '订阅', link: '/config/subscriptions' },
{ text: '欢迎弹窗', link: '/config/welcome-popup' },
{ text: '微信读书', link: '/config/weread' },
{ text: '记得', link: '/config/important-dates' },
{ text: '留言板', link: '/config/messageboard' },
{ text: '评论', link: '/config/comment' },
@@ -53,7 +55,7 @@ export default defineConfig({
{ text: '瞬间', link: '/pages/moments' },
{ text: '图库', link: '/pages/photos' },
{ text: '友情链接', link: '/pages/links' },
{ text: '朋友圈', link: '/pages/friends' },
{ text: '订阅', link: '/pages/subscriptions' },
{ text: '记得', link: '/pages/important-dates' },
{ text: '自定义页面', link: '/pages/custom-page' },
{ text: '扩展页面', link: '/pages/extended' },
docs/changelog.md
+35
View File
@@ -1,5 +1,40 @@
# 更新日志
## v1.2.7
### 文档全面校准（与最新版主题对齐）
- 🔌 **移除「朋友圈」插件的全部使用说明**：`plugin-friends` 已不再提供，原先的 feed / RSS 聚合能力
由官方 **「链接管理」（PluginLinks）插件的订阅**承担。主题的对应实现是 `page_subscriptions.html`
自定义模板与 `subscriptions` 设置分组；新增订阅配置 / 订阅页面文档，删除旧的朋友圈配置与页面文档
- 📌 主题保留 `friends.html` 模板与「朋友圈」设置分组**仅用于兼容旧站点**，`pluginFinder` 检测不到
该插件时会显示空状态；新站点请勿再依赖，文档已明确标注
- ⬆️ 全文统一 Halo 版本要求为 **2.27.0+**（`docs/guide/getting-started.md` 原写 `2.24.0`，与
`theme.yaml` 的 `requires: ">=2.27.0"` 不一致）
- 🧹 清理与代码不符的描述：已移除的光感跟随 `animation_cursor_glow`、主题并不自带的
i18n 国际化、没有对应模板的「足迹页面」；`docs/config/style.md` 补上实际存在的
`click_effect_enabled` / `click_effect_type`
- 📚 补齐此前完全没有文档的三个设置分组：**欢迎弹窗、订阅、微信读书**；自定义页面模板清单
同步为 4 个（默认 / 留言板 / 订阅 / 微信读书）
- 🔢 配置数量统一为 **17 组 / 126 项**，插件适配表按实际 **10 款**校准，VitePress 侧边栏同步调整
- 🔗 所有文档内部相对链接复核为 0 处失效
### 可选 API 设置项文案精简
- ✂️ 主题设置中「自定义 IP 定位主 API」「自定义 IP 定位备选 API」「自定义一言 API」
三个配置项的 `help` 移除三段冗长的隐私披露文案，仅保留功能说明（候选接口地址、留空回退规则）
- 🛡️ 第三方数据流向与隐私披露仍由 README「外部资源与隐私」章节、配置文档与 FAQ 完整承载，
满足 5.1 要求；设置界面文案精简不影响「默认零第三方请求」的结论
- ↩️ 三个字段恢复按功能开关条件显示（「启用欢迎弹窗」开关 / 「描述文案来源」），与 v1.2.6
的设计一致；同时修正三个配置块的缩进，与 `settings.yaml` 其余字段对齐
- 🔒 `pnpm audit:external` 的 5.1 检查改为：三个字段必须存在、`help` 不得回潮出现披露文案、
README 必须保留隐私披露章节
### 正文引用块留白（与上一轮改动合并）
- 🎨 修复文章 / 单页 / 留言板正文引用块文字下方空白过大：块内元素外边距与 `padding` 叠加导致
双层留白，现统一收敛，并折叠编辑器生成的空段落；引用块上下外边距同步收紧
## v1.2.6
> v1.2.5 为审核被拒的未发布版本，从未对外分发；其全部整改内容纳入 v1.2.6 一并发布。
docs/config/article.md
+2
View File
@@ -22,6 +22,8 @@
| `article_related_title` | 文本 | `相关推荐` | 相关文章标题 |
| `article_show_share` | 开关 | `true` | 显示分享按钮 |
| `article_share_title` | 文本 | `分享` | 分享区域标题 |
| `article_extra_spacing` | 开关 | `true` | 中英文混排自动加空格；依赖「API 扩展包」，插件未安装时自动跳过 |
| `article_extra_highlight` | 开关 | `false` | 服务端代码高亮；依赖「API 扩展包」全量版（含 JS 运行时），开启后替代主题自带配色，环境不支持请勿开启 |
## 详细说明
docs/config/basic.md
+2 -17
View File
@@ -13,7 +13,6 @@
| `label_search` | 文本 | `搜索` | 搜索按钮的标签文案 |
| `label_theme_switch` | 文本 | `切换主题` | 主题切换按钮的标签文案 |
| `label_archives_title` | 文本 | `归档` | 归档页面的标题文案 |
| `language` | 下拉 | `auto` | 主题界面语言 |
## 详细说明
@@ -70,22 +69,8 @@ label_archives_title: "Archives"
```
::: tip
标签文案的修改会即时生效，无需重启 Halo。如果使用多语言场景，可以配合 Halo 的多语言插件实现更完整的国际化。
:::
### 语言（language）
设置主题界面的显示语言，影响导航栏、文章页、错误页等所有主题内置文案。提供以下选项：
| 值 | 说明 |
| --- | --- |
| `auto` | 跟随浏览器语言自动匹配（默认） |
| `zh_CN` | 简体中文 |
| `zh_TW` | 繁體中文 |
| `en` | English |
::: tip
选择 `auto` 时，主题会根据访客浏览器的语言设置自动匹配最接近的语言。如果浏览器语言不在支持列表中，将回退到简体中文。
标签文案的修改会即时生效，无需重启 Halo。主题**不内置界面语言切换 / 多语言包**，
需要多语言站点时请使用 Halo 或相应插件提供的能力；主题内置的少量界面文案可通过上方 3 个标签项自定义。
:::
## 相关页面
docs/config/footer.md
+6
View File
@@ -12,6 +12,12 @@
| `footer_show_powered` | 开关 | `true` | 显示「Powered by Halo」 |
| `footer_show_theme` | 开关 | `true` | 显示主题版本 |
| `footer_custom_html` | 代码 | — | 自定义 HTML（统计代码等） |
| `footer_show_stats` | 开关 | `true` | 在页脚显示全站统计 |
| `footer_stats_items` | 多选 | `post,category,comment,visit` | 统计项：`post` 文章 / `category` 分类 / `comment` 评论 / `visit` 访问 / `upvote` 点赞 / `word` 总字数（总字数依赖「API 扩展包」，未安装时自动隐藏） |
| `footer_show_icp` | 开关 | `false` | 显示 ICP 备案号（开启后 `footer_icp` 才会显示） |
| `footer_show_mps` | 开关 | `false` | 显示公网安备号与徽标 |
| `footer_mps` | 文本 | — | 公网安备号（需开启上方开关） |
| `footer_mps_url` | 文本 | — | 公网安备跳转链接，留空默认 `https://beian.mps.gov.cn/` |
## 详细说明
docs/config/friends.md
-62
View File
@@ -1,62 +0,0 @@
# 朋友圈
朋友圈模块用于聚合展示你订阅的站点最新动态，类似于 RSS 阅读器的社交化呈现。访客可以在你的站点上浏览友站最新文章，发现更多优质内容。
## 配置项一览
| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `friends_page_title` | 文本 | `朋友圈` | 页面标题 |
## 前置依赖
::: danger
朋友圈功能依赖 Halo 的 **plugin-friends** 插件。如果未安装此插件，朋友圈页面将无法正常工作。
安装方式：Halo 后台 → **插件** → **安装** → 搜索「朋友圈」或从 [GitHub Releases](https://www.halo.run/store/apps/app-yISsV) 下载安装。
:::
## 详细说明
### 页面标题（friends_page_title）
朋友圈页面的标题，显示在页面顶部。
```yaml
friends_page_title: "朋友圈" # 默认
friends_page_title: "友圈" # 简称
friends_page_title: "Friends" # 英文站点
```
## RSS 订阅说明
朋友圈的核心机制是通过 RSS 订阅聚合友站内容：
1. 在 Halo 后台的 Friends 插件设置中添加友站的 RSS 订阅地址
2. 插件会定期抓取这些 RSS 源的最新文章
3. 朋友圈页面按时间倒序展示所有订阅源的最新文章
### 添加订阅源
1. 登录 Halo 后台管理控制台
2. 进入 **链接** 管理页面
3. 点击 **新建** 或 **编辑** 填写：元数据 **RSS 地址** 友站的 RSS 订阅地址
4. 保存后，插件会在下次抓取周期自动拉取内容，亦可进入 **朋友圈** 自行同步
::: tip
大多数博客平台都提供 RSS 订阅功能。常见的 RSS 地址格式：
- WordPress：`/feed/`
- Halo：`/rss.xml` 或 `/feed/`
- Hexo：`/atom.xml` 或 `/rss2.xml`
- Typecho：`/feed/`
:::
::: warning
RSS 抓取频率取决于插件配置，通常为每 30 分钟到数小时一次。新添加的订阅源可能需要等待一个抓取周期才能在页面显示内容。
:::
## 相关页面
- [友情链接](/config/links) — 友情链接页面配置
- [页脚](/config/footer) — 页脚社交链接配置
- [朋友圈页面](/pages/friends) — 朋友圈模板与结构说明
docs/config/hero.md
+15 -8
View File
@@ -10,7 +10,7 @@ Hero 首屏是 WarmIsland 主题的标志性区域，占据首页首屏的全部
| `hero_title` | 文本 | — | 主标题（留空则使用站点标题） |
| `hero_subtitle` | 文本 | — | 副标题（留空则使用站点副标题） |
| `hero_description_mode` | 下拉 | `none` | 描述文案来源：`none` / `hitokoto` / `custom`，默认不显示描述文案 |
| `hero_hitokoto_api` | URL | `https://v1.hitokoto.cn/` | 选「一言」时自动填入官方接口；留空则使用内置本地句子库（零外部请求） |
| `hero_hitokoto_api` | URL | `https://v1.hitokoto.cn/` | 默认预填官方接口（描述来源非「无」时显示，仅「一言」模式生效）；清空则使用内置本地句子库（零外部请求） |
| `hero_hitokoto_categories` | 多选 | `d, i, k` | 句子类型筛选，仅对自定义 API 生效 |
| `hero_custom_description` | 多行文本 | — | 自定义描述文案 |
| `hero_hitokoto_auto_refresh` | 开关 | `false` | 一言自动刷新 |
@@ -49,23 +49,30 @@ hero_subtitle: "记录温暖与灵感"
| 值 | 说明 |
| --- | --- |
| `none` | **默认**。不显示描述文案，不渲染一言元素，也不发起任何请求 |
| `hitokoto` | 显示一句话文案；自动填入官方接口 `https://v1.hitokoto.cn/`，清空该字段则使用内置本地句子库 |
| `hitokoto` | 显示一句话文案；API 字段默认预填官方接口 `https://v1.hitokoto.cn/`，清空该字段则使用内置本地句子库 |
| `custom` | 显示自定义的描述文案（静态文本，不发起任何请求） |
### 一言模式（hitokoto）
默认 `none` 时一言元素不渲染。切换到 `hitokoto` 后，设置项「自定义一言 API」自动填入
`https://v1.hitokoto.cn/`，浏览器会向该地址发起 GET 请求获取句子（第三方可见访客 IP / User-Agent）。
默认 `none` 时一言元素不渲染。「自定义一言 API」设置项在描述来源非「无」时显示，并默认预填
`https://v1.hitokoto.cn/`；切换到 `hitokoto` 后该值生效，浏览器会向该地址发起 GET 请求
获取句子（第三方可见访客 IP / User-Agent）。
若把该字段清空，则回退到主题内置的本地句子库 `assets/data/hitokoto.json`
（随主题自托管的静态 JSON，零外部请求），每次刷新随机展示一条，也不会因为第三方接口不可用而出现空白。
可直接编辑该 JSON 替换成自己喜欢的句子。
#### 自定义一言 API（hero_hitokoto_api）
选择「一言」或「自定义」后才会显示该设置项。选择「一言」时自动填入 `https://v1.hitokoto.cn/`；
**选择「一言」或「自定义」后若留空，则使用主题内置的本地句子库（零外部请求）**。
**只有填写后才会向该地址发起请求**，需自行在站点隐私说明中披露，详见 README「外部资源与隐私」。
也可换成自建实例或其他兼容接口。
该设置项在「描述文案来源」非「无」时显示，`help` 只说明候选地址与留空回退规则；
字段默认预填 `https://v1.hitokoto.cn/`，**仅在「一言」模式下生效**。
**选择「一言」或「自定义」后若把该字段留空，则使用主题内置的本地句子库（零外部请求）**。
只有填写后才会向该地址发起请求，第三方可见访客 IP / User-Agent；完整的数据流向与隐私披露
见 README「外部资源与隐私」章节。也可换成自建实例或其他兼容接口。
::: tip
「描述文案来源」默认「无」时一言元素不渲染，因此即使字段预填了官方地址，
也不会产生任何外部请求。隐私披露统一在 README 与本文档说明，设置界面不重复展示。
:::
::: warning
这是站点管理员主动开启的可选能力。把描述文案来源改回「无」、或清空该字段即可随时停止外部请求，无需重装主题。
docs/config/links.md
+9 -1
View File
@@ -6,8 +6,12 @@
| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `links_apply_form_enabled` | 开关 | `true` | 页底显示友链申请表单；需插件开启「友链申请」，否则自动隐藏 |
| `links_page_title` | 文本 | `友情链接` | 页面标题 |
| `links_style` | 下拉 | `cards` | 展示样式：`grid` / `list` / `cards` |
| `links_show_comment` | 开关 | `false` | 页面底部显示评论区 |
| `links_random_order` | 开关 | `false` | 友链卡片随机排列 |
| `links_random_portal` | 开关 | `true` | 页面右上角显示「随机传送」按钮 |
## 前置依赖
@@ -15,6 +19,9 @@
友情链接功能依赖 Halo 的 **PluginLinks** 插件。如果未安装此插件，友情链接页面将无法正常工作。
安装方式：Halo 后台 → **插件** → **安装** → 搜索「链接管理」→ 安装并启用。
同一个插件还提供 **RSS 订阅能力**（原「朋友圈」插件的 feed 聚合功能已由它取代），
对应主题的[订阅配置](/config/subscriptions)与[订阅页面](/pages/subscriptions)。
:::
## 详细说明
@@ -65,6 +72,7 @@ PluginLinks 支持链接分组功能。你可以将友链按不同类别分组
## 相关页面
- [朋友圈](/config/friends) — 朋友圈页面配置
- [订阅配置](/config/subscriptions) — 同一插件提供的 RSS 订阅动态
- [订阅页面](/pages/subscriptions) — 博友文章动态页面
- [页脚](/config/footer) — 页脚社交链接配置
- [友情链接页面](/pages/links) — 友链模板与结构说明
docs/config/moments.md
+1
View File
@@ -10,6 +10,7 @@
| `moments_style` | 下拉 | `cards` | 展示样式：`cards` / `masonry` |
| `moments_loading_mode` | 下拉 | `infinite_scroll` | 加载方式：`infinite_scroll` / `pagination` |
| `moments_page_size` | 数字 | `10` | 每页显示数量 |
| `moments_cover` | 附件 | — | 瞬间页顶部封面图，建议尺寸 1500×500 |
## 前置依赖
docs/config/navbar.md
+3
View File
@@ -9,6 +9,9 @@
| `navbar_style` | 下拉 | `glass` | 导航栏样式：`glass` / `minimal` / `float` |
| `navbar_show_search` | 开关 | `true` | 显示搜索按钮 |
| `navbar_show_theme_switch` | 开关 | `true` | 显示主题切换按钮 |
| `navbar_brand_type` | 下拉 | `title` | 左侧显示：`title` 站点名称 / `logo` Logo |
| `navbar_logo` | 附件 | — | 导航栏 Logo；仅在「Logo」模式下显示，留空回退到基础设置的自定义 Logo |
| `navbar_logo_radius` | 下拉 | `rounded` | Logo 圆角：`square` / `rounded` / `circle`（Logo 模式下生效） |
## 详细说明
docs/config/style.md
+6 -7
View File
@@ -14,7 +14,8 @@
| `animation_enabled` | 开关 | `true` | 全局动画总开关 |
| `animation_breath` | 开关 | `true` | 呼吸动画效果 |
| `animation_scroll_reveal` | 开关 | `true` | 滚动渐入动画 |
| `animation_cursor_glow` | 开关 | `false` | 光感跟随效果 |
| `click_effect_enabled` | 开关 | `false` | 鼠标点击效果总开关 |
| `click_effect_type` | 下拉 | `values` | 点击效果类型（8 种效果 + 关闭，仅在总开关开启时显示） |
| `custom_css` | 代码 | — | 自定义 CSS 代码 |
## 详细说明
@@ -121,13 +122,11 @@ WarmIsland 提供了丰富的动画效果，所有动画都可以独立开关：
滚动渐入动画基于 Intersection Observer API 实现，对性能影响极小。如果页面内容较多，建议保持开启以提升浏览体验。
:::
#### 光感跟随（animation_cursor_glow）
#### 鼠标点击效果（click_effect_enabled / click_effect_type）
启用后，鼠标移动时会在光标附近产生柔和的光晕跟随效果，为页面增添灵动感。
::: warning
光感跟随效果在移动端不会生效（因为移动端没有鼠标光标）。在低端设备上可能会影响渲染性能，如遇卡顿建议关闭。
:::
`click_effect_enabled` 默认关闭；开启后 `click_effect_type` 才会显示，可选 8 种效果：
社会主义核心价值观、随机彩色爱心、烟花、烟花波纹、粒子、星星、星星拖尾、粒子拖尾，
另可选「关闭」。特效在访客点击时由浏览器本地绘制，不加载远程脚本、不发送任何数据。
### 自定义 CSS（custom_css）
docs/config/subscriptions.md
+59
View File
@@ -0,0 +1,59 @@
# 订阅
订阅模块用于展示博友们的最新文章动态（feed / RSS 聚合）。这项能力由 **Halo 官方「链接管理」（PluginLinks）插件的订阅**提供，主题只负责把插件抓取到的订阅动态渲染成页面。
> `plugin-friends`（朋友圈）插件已不再提供，原来的 feed 聚合功能由链接管理插件的订阅取代。
> 主题中的 `friends.html` 模板与「朋友圈」设置分组仅用于兼容旧站点，新站点请使用订阅页面模板，
> 详见[历史兼容说明](#历史兼容说明)。
## 配置项一览
| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `subscriptions_page_title` | 文本 | `订阅` | 页面标题 |
| `subscriptions_subtitle` | 文本 | `博友们的最新文章` | 页面副标题 |
| `subscriptions_page_size` | 数字 | `20` | 每页展示的动态条数，范围 1–100 |
| `subscriptions_loading_mode` | 下拉 | `pagination` | `pagination` 分页 / `infinite_scroll` 下滑加载 |
| `subscriptions_layout` | 下拉 | `list` | `list` 列表卡片 / `grid` 网格卡片 |
## 前置依赖
::: danger
订阅页面依赖 Halo 官方 **「链接管理」（PluginLinks）** 插件的 RSS 订阅能力，
可在[应用市场](https://www.halo.run/store/apps/app-hfbQg)安装。未安装或未启用订阅时，
页面会显示空状态提示，不会报错。
:::
订阅源由链接管理插件维护（为博友链接配置 RSS 订阅地址、按插件自身的周期抓取），
主题通过 Halo 的 `linkFeedFinder` 读取已抓取的动态列表，不自行抓取、不缓存、不向第三方发起请求。
订阅源的添加入口与抓取频率以所安装插件版本的说明为准。
## 详细说明
### 加载方式（subscriptions_loading_mode）
- `pagination`：页面底部显示「较新 / 较旧」翻页链接，按时间游标分页。
- `infinite_scroll`：滚动到列表底部时自动加载下一页，并显示加载状态与「没有更多了」提示。
### 布局样式（subscriptions_layout）
- `list`：单列宽卡片，默认布局，适合长摘要阅读。
- `grid`：一行三列（窄屏自动降为两列 / 一列），卡片内容垂直排列。
两种方式下每条动态都展示作者头像 / 名称、发布日期、文章标题与摘要，标题与作者链接均带
`rel="noopener noreferrer"`；作者名为空时会显示占位字符，不会因字符串截取报错。
## 历史兼容说明
主题仍保留 `templates/friends.html` 与设置中的「朋友圈」分组（`friends_page_title`），
它们只读取旧 `plugin-friends` 插件的数据。该插件已不再提供，因此：
- 新站点**不要**再创建 `/friends` 页面或依赖这个分组；
- 旧站点若已停用该插件，`friends.html` 会显示空状态而不会报错；
- 需要 feed 聚合时，请改用 `page_subscriptions.html` 订阅模板。
## 相关页面
- [订阅页面](/pages/subscriptions) — 页面结构、模板选择与迁移说明
- [友情链接配置](/config/links) — 同一插件的友链展示配置
- [自定义页面](/pages/custom-page) — 全部自定义页面模板
docs/config/welcome-popup.md
+44
View File
@@ -0,0 +1,44 @@
# 欢迎弹窗
欢迎弹窗在首页以浮层形式向访客打招呼。**默认关闭**，开启后也只显示主题内置的本地静态欢迎语，
不会自动向任何第三方发起请求。
## 配置项一览
| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `welcome_popup_enabled` | 开关 | `false` | 启用欢迎弹窗 |
| `welcome_popup_position` | 下拉 | `top-center` | 弹窗位置，共 5 种 |
| `welcome_popup_duration` | 数字 | `5` | 自动消失时间（秒），范围 3–60 |
| `welcome_popup_show_once` | 开关 | `true` | 同一浏览器会话内仅显示一次 |
| `welcome_popup_api` | URL | 留空 | 自定义 IP 定位主 API（可选） |
| `welcome_popup_fallback_api` | URL | 留空 | 自定义 IP 定位备选 API（可选） |
## 弹窗位置
| 值 | 位置 |
| --- | --- |
| `top-center` | 顶端居中（默认） |
| `top-left` / `top-right` | 左上 / 右上 |
| `bottom-left` / `bottom-right` | 左下 / 右下 |
`welcome_popup_show_once` 使用浏览器 `sessionStorage` 记录同会话已显示状态；
关闭该开关后每次访问首页都会弹出。清除浏览器站点数据即可重置。
## 可选的 IP 定位能力（默认关闭）
两个 API 字段仅在「启用欢迎弹窗」开关打开时显示，`help` 只说明候选地址与留空规则；
第三方数据流向与隐私披露由本文档下方条目及 README「外部资源与隐私」章节承载。
字段**默认留空**，此时弹窗只显示本地欢迎语，不发起任何外部请求。
只有管理员显式填写后，浏览器才会向该地址请求并把**访客 IP**暴露给第三方服务以换取粗略地理位置：
- 候选主 / 备选接口：`https://myip.ipip.net/json`、`https://r.inews.qq.com/api/ip2city?otype=json`
- 数据流向与隐私披露要求见 README「外部资源与隐私」章节
- 清空字段或关闭弹窗即可立即停止，无需重装主题
> 主题不预置、不代理这些接口，也不保存访客位置数据；填写前请自行评估服务商的隐私政策。
## 相关页面
- [基础设置](/config/basic) — 站点名称、Logo 等
- [首页](/pages/home) — 首页模块说明
docs/config/weread.md
+30
View File
@@ -0,0 +1,30 @@
# 微信读书
微信读书模块用于展示书架与阅读记录，主题提供 `weread.html` 自定义页面模板，
数据由[微信读书插件](https://github.com/yeora26/halo-weread-plugin)提供，访客无需登录即可查看。
::: info
该页面依赖 Halo **2.27+** 的能力；主题声明的兼容范围为 `>=2.27.0`。
:::
## 配置项一览
| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `weread_page_title` | 文本 | — | 页面标题（顶部标题与浏览器标签页标题）；插件自带的标题区会自动隐藏以避免重复 |
| `weread_page_subtitle` | 文本 | — | 页面副标题 |
留空时由模板回退到默认文案，不会导致页面报错。
## 使用方式
1. 安装并启用微信读书插件
2. Halo 后台 → **页面** → **新建** → 自定义模板选择「**微信读书**」（`WeRead`）
3. 发布页面并加入导航菜单
页面地址由创建页面时设定的 slug 决定，主题不提供固定路由。
## 相关页面
- [自定义页面](/pages/custom-page) — 全部自定义页面模板
- [扩展页面](/pages/extended) — 插件前台页面一览
docs/customize/development.md
+2 -2
View File
@@ -125,7 +125,7 @@ WarmIsland/
│ │ # LightGallery / ClickEffect / ScrollReveal / ThemeSwitcher 等
│ ├── layouts/ # Layout.astro（含页面布局契约渲染模式）
│ ├── pages/ # index / post / page / archives / categories / category /
│ │ # tags / tag / links / friends / moments / moment / photos /
│ │ # tags / tag / links / friends（历史兼容）/ moments / moment / photos /
│ │ # douban / equipments / important-dates / steam / weread /
│ │ # page_messageboard / page_subscriptions / layout
│ └── styles/ # main.scss + 12 个 _*.scss 片段
@@ -154,7 +154,7 @@ WarmIsland/
| 技术 | 版本 | 用途 |
|------|------|------|
| [Halo](https://www.halo.run/) | 2.27+ | 博客运行时，提供 Finder API 与主题渲染 |
| [Halo](https://www.halo.run/) | 2.27.0+ | 博客运行时，提供 Finder API 与主题渲染 |
| [Astro](https://astro.build) | 6.x | 组件开发，构建输出静态 `.html` 模板 |
| [Thymeleaf](https://www.thymeleaf.org/) | - | Halo 服务端模板引擎（源码里直接写 `th:*`） |
docs/customize/style.md
+2 -1
View File
@@ -202,6 +202,7 @@ else if (!stored && prefersDark) { isDark = true; }
| `animation_enabled` | 启用动效 | `true` |
| `animation_breath` | 呼吸动画 | `true` |
| `animation_scroll_reveal` | 滚动渐入 | `true` |
| `animation_cursor_glow` | 光感跟随 | `false` |
| `click_effect_enabled` | 鼠标点击效果 | `false` |
| `click_effect_type` | 点击效果类型（8 种 + 关闭） | `values` |
关闭动效时，`html` 元素添加 `wi-no-animations` 类名。
docs/faq.md
+21 -7
View File
@@ -116,10 +116,23 @@ v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖
| 瞬间 | [PluginMoments](https://www.halo.run/store/apps/app-SnwWD) |
| 图库 | [PluginPhotos](https://www.halo.run/store/apps/app-BmQJW) |
| 友链 | [PluginLinks](https://www.halo.run/store/apps/app-hfbQg) |
| 朋友圈 | [PluginFriends](https://www.halo.run/store/apps/app-yISsV) |
| 订阅动态 | 同为 [PluginLinks](https://www.halo.run/store/apps/app-hfbQg) 的 RSS 订阅能力，需选择「订阅」自定义模板 |
安装并启用插件后，页面会自动显示内容。未安装插件时页面会显示友好的提示信息。
**「朋友圈」插件已不再提供**：feed / RSS 聚合已由官方「链接管理」插件的订阅取代，
主题保留 `friends.html` 模板与「朋友圈」设置分组仅用于兼容旧站点。新站点请新建页面并选择
「订阅」自定义模板，详见 README「自定义页面模板」与[订阅页面](https://nxxy335.top/WarmIsland/pages/subscriptions.html)。
### 原来的「朋友圈」页面不能用了，怎么迁移？
1. 安装 / 启用官方「链接管理」（PluginLinks）插件，把 RSS 订阅源迁到该插件的订阅中
2. Halo 后台 → 页面 → 新建 → 自定义模板选择「订阅」（`page_subscriptions.html`）
3. 在主题设置 → 订阅中调整每页条数、分页 / 下滑加载与列表 / 网格布局
4. 确认动态正常展示后，删除旧的 `/friends` 页面与菜单项
旧的 `friends.html` 检测不到 `plugin-friends` 时只会显示空状态，不会影响站点其他页面。
### 主题会向第三方服务发请求吗？
**默认不会。** 所有脚本、样式、字体、图标、主题 Logo 与一言句子库都随主题自托管，
@@ -128,14 +141,14 @@ v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖
1. 访客**主动点击**分享按钮 / 备案链接 / 应用市场链接时才跳转到对应站点；
2. 站点管理员在主题设置里**显式填写**了「自定义一言 API」或「自定义 IP 定位 API」——
后者会把访客 IP 发送给该第三方服务换取地理位置，**需自行在站点隐私说明中披露**，
详见 README「外部资源与隐私」。
后者会把访客 IP 发送给该第三方服务换取地理位置；数据流向与披露要求见
README「外部资源与隐私」。
可选接口地址（仅作候选，主题不会自动请求）：
| 能力 | 可选地址 |
| --- | --- |
| 一言 | `https://v1.hitokoto.cn/`（选择「一言」时自动填入） |
| 一言 | `https://v1.hitokoto.cn/`（默认预填，仅「一言」模式生效） |
| IP 定位主 / 备选 API | `https://myip.ipip.net/json`、`https://r.inews.qq.com/api/ip2city?otype=json` |
完整逐项说明见 README 的「外部资源与隐私」章节。发版前可运行 `pnpm audit:external` 复核。
@@ -144,10 +157,11 @@ v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖
1. Hero「描述文案来源」**默认为「无」**，此时不显示描述文案、不渲染一言元素，零外部请求；
想显示句子请改为「一言」
2. 选择「一言」后会自动填入 `https://v1.hitokoto.cn/`，此时才会产生外部请求；
2. 「自定义一言 API」字段在「描述文案来源」非「无」时显示，且默认预填 `https://v1.hitokoto.cn/`，
选择「一言」后该值才生效并产生外部请求；
**把该字段清空即回退到主题内置的 `assets/data/hitokoto.json` 本地句子库（零外部请求）**，
直接编辑该 JSON 即可替换文案。只有填写后才会向该地址发起请求，需自行在站点隐私说明中披露，
详见 README「外部资源与隐私」
直接编辑该 JSON 即可替换文案。只有填写后才会向该地址发起请求，数据流向与披露要求见
README「外部资源与隐私」
3. 「自定义」模式显示「自定义描述文案」中的静态文本，不发起任何请求；
「句子类型」筛选仅对填写了 API 的一言模式生效
docs/guide/getting-started.md
+20 -6
View File
@@ -8,13 +8,15 @@ WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主
- 🌙 **深色模式** — 跟随系统/浅色/深色三种方案，平滑切换
- 📱 **响应式布局** — 桌面到手机完美适配
- 📝 **沉浸阅读** — 侧边目录、进度条、代码高亮、图片灯箱
- 🔌 **插件生态** — 瞬间、图库、友链、朋友圈、豆瓣、装备、Steam
- ⚙️ **灵活配置** — 全维度自定义面板，无需改代码
- 🔌 **插件生态** — 瞬间、图库、友链、订阅动态、豆瓣、装备、Steam
- 🔒 **默认零第三方请求** — 静态资源全部自托管，可选 API 默认留空
- ⚙️ **灵活配置** — 17 个分组 / 126 个配置项，无需改代码
## 前置要求
- Halo >= 2.24.0
- **Halo >= 2.27.0**（主题 `theme.yaml` 声明 `requires: ">=2.27.0"`；页面布局契约与微信读书页面依赖 2.27 的能力）
- 已安装并运行 Halo 实例
- 如需插件页面（瞬间、图库、友链、订阅等），另需安装对应插件
## 安装方式
@@ -33,6 +35,11 @@ WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主
4. 上传下载的 `.zip` 文件
5. 点击 **启用** 激活主题
::: warning
从源码自行打包时，必须先执行 `pnpm release`（build → snapshot → package）。
只上传源码或漏跑构建的 ZIP 会因缺少 `templates/` 导致首页 404，详见 [FAQ](/faq)。
:::
## 初始配置
安装并启用主题后，建议按以下顺序进行初始配置：
@@ -49,8 +56,8 @@ WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主
进入 **样式设置**：
- 选择 **配色方案**（跟随系统/浅色/深色）
- 设置 **强调色**（默认 `#d4764e` 暖橘色）
- 选择 **配色方案**（跟随系统/浅色/深色）与 **主题配色**（11 套预设）
- 设置 **强调色**（留空则跟随所选配色，暖屿·赤陶为 `#d4764e`）
- 选择 **圆角风格** 和 **容器宽度**
### 第三步：导航菜单
@@ -64,7 +71,7 @@ WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主
进入 **Hero 首屏** 设置：
- 设置主标题和副标题
- 选择描述文案来源（默认「无」/ 一言 / 自定义）；默认不显示描述、不发起请求；选「一言」自动填入 `https://v1.hitokoto.cn/`，清空该字段则使用内置本地句子库（零外部请求）
- 选择描述文案来源（默认「无」/ 一言 / 自定义）；默认不显示描述、不发起请求；「自定义一言 API」字段在来源非「无」时显示并默认预填 `https://v1.hitokoto.cn/`（仅「一言」模式生效），清空该字段则使用内置本地句子库（零外部请求）
- 可选上传背景图片
### 第五步：页脚信息
@@ -75,7 +82,14 @@ WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主
- 添加社交链接（GitHub、微博等）
- 可选添加自定义 HTML（统计代码等）
### 可选：订阅动态页面
如需展示博友文章动态，安装官方「链接管理」（PluginLinks）插件并维护 RSS 订阅源，
再新建一个页面选择「订阅」自定义模板即可。原先的「朋友圈」插件已不再提供，
详见[订阅页面](/pages/subscriptions)。
## 下一步
- [基础设置](/config/basic) — 完整的主题配置说明
- [样式设置](/config/style) — 调整配色、圆角、动画
- [订阅配置](/config/subscriptions) — feed 聚合动态设置
docs/guide/introduction.md
+29 -14
View File
@@ -2,10 +2,15 @@
**WarmIsland（暖屿）** 是一款为 [Halo](https://halo.run) 打造的博客主题。暖如灯火，静如留白——它以柔和的色调和舒缓的节奏回归内容本身，为记录与阅读留出一方安静从容的角落。
> 本主题由 AI 开发完成。
> 本项目使用 AI 辅助开发，产出已由开发者完成代码审查、构建产物核验与 Halo 开发生态适配。
它的名字来源于一个画面——深夜里温暖的小岛。我们希望每一个来到你站点的访客，都能感受到那份安静而舒适的氛围。
## 环境要求
- Halo **2.27.0 及以上**（`theme.yaml` 的 `requires` 为 `>=2.27.0`）：页面布局契约、微信读书页面均依赖 2.27 的能力
- v1.2.0 起内置主题配色系统（纯 CSS 变量实现）；更低版本的 Halo 请使用主题 v1.1.x
## 设计理念
暖屿的设计围绕三个核心词展开：**温暖、沉浸、精致**。
@@ -28,19 +33,20 @@
- **暖色调设计语言** — 橘色强调色 + 呼吸光球 + 渐变背景
- **三种导航栏样式** — Glass（毛玻璃）/ Minimal（极简）/ Float（浮动胶囊）
- **内置配色系统** — 11 套预设调色板，每套含浅色 / 深色完整色板
- **深色模式** — 跟随系统、浅色、深色三种方案，一键切换平滑过渡
- **动效系统** — 滚动渐入、光感跟随、呼吸动画，均可独立开关
- **动效系统** — 滚动渐入、呼吸动画、点击特效，均可独立开关
### 📝 阅读体验
- **文章目录** — 桌面端侧边悬浮 + 移动端底部抽屉，支持展开模式选项
- **阅读进度条** — 实时显示阅读进度
- **代码高亮** — 由代码高亮插件 / API 扩展包输出，主题提供 Warm / Cold 本地配色，不加载远程脚本
- **图片灯箱** — 点击放大，支持左右切换
- **图片灯箱** — 点击放大，支持左右切换与 EXIF 信息
- **图片懒加载** — blur-up 渐显效果，优化加载体验
- **点赞功能** — 一键点赞，状态持久化
- **相关文章推荐** — 文章底部推荐相关内容
- **分享功能** — 微博 / X / Facebook / Telegram / 复制链接
- **分享功能** — QQ / 微博 / X / Facebook / Telegram / 复制文章链接
### 📱 响应式
@@ -49,11 +55,10 @@
- 文章卡片自动切换为上下布局
- 目录自动切换为悬浮按钮 + 抽屉
### 🔍 SEO 与国际化
### 🔍 SEO 与结构化数据
- **Open Graph 元标签** — 优化社交媒体分享预览
- **JSON-LD 结构化数据** — 提升搜索引擎理解与展示
- **i18n 国际化** — 简体中文、繁体中文、英语，支持跟随浏览器自动匹配
- **JSON-LD 结构化数据** — 文章标题 / 作者 / 日期 / 封面，由转义后的 `<meta>` 生成，不拼接不可信字符串
### 🔌 插件生态
@@ -64,28 +69,38 @@
| 瞬间 | PluginMoments | Timeline / Cards / Masonry 三种布局 |
| 图库 | PluginPhotos | Masonry / Grid / Carousel + 分组浏览 |
| 友情链接 | PluginLinks | Cards / Grid / List 三种布局 |
| 朋友圈 | plugin-friends | 友站动态时间线 |
| 订阅 | PluginLinks（RSS 订阅） | 博友文章动态，分页 / 下滑加载、列表 / 网格布局 |
| 豆瓣 | 豆瓣插件 | 观影/读书/音乐记录 |
| 装备 | 装备插件 | 按分组展示装备清单 |
| Steam | Steam 插件 | 游戏资料与徽章 |
| 记得 | plugin-important-dates | 重要日期 / 牵挂的人 / 爱车双视图 |
> 「朋友圈」（`plugin-friends`）插件已不再提供，其 feed 聚合能力由官方「链接管理」插件的订阅取代，
> 详见[订阅页面](/pages/subscriptions)。
### ⚙️ 灵活配置
17 个配置分组、120 余个配置项，覆盖站点的方方面面：
17 个配置分组、126 个配置项，覆盖站点的方方面面：
- 基础信息、样式、导航栏、Hero 首屏
- 首页、文章、瞬间、图库、友情链接
- 朋友圈、留言板、评论、页脚
- 基础信息、样式、导航栏、Hero 首屏、欢迎弹窗
- 首页、文章、瞬间、图库、友情链接、订阅
- 微信读书、记得、留言板、评论、页脚
所有配置都在 Halo 后台的图形化面板中完成，无需修改代码。
### 🔒 默认零第三方请求
全部脚本、样式、字体、图标、句子库与主题 Logo 随主题自托管；Hero 描述文案默认「无」、
欢迎弹窗默认关闭、两个可选 API 字段默认留空，页面不会自动向第三方发起请求。
详见 README「外部资源与隐私」。
## 技术栈
- **Astro 6** — 构建输出 Thymeleaf 模板
- **Thymeleaf** — Halo 使用的服务端模板引擎
- **原生 JavaScript + SCSS** — 交互与样式（无 Vue / 无远程运行时）
- **LightGallery 2.9.0（GPLv3）** — 图片灯箱，随构建自托管打包
- **LXGW WenKai（OFL 1.1）** — 本地字体分片，无远程字体请求
- **LXGW WenKai（OFL 1.1）** — 本地字体分片，许可证全文随包分发
- **代码高亮** — 交由 Halo 应用市场插件提供，主题只自托管配色 CSS
## 适用场景
@@ -95,7 +110,7 @@ WarmIsland 适合以下类型的站点：
- 📖 **个人博客** — 记录生活、分享思考
- 📸 **摄影站** — 图库页面展示作品
- 🎮 **游戏博客** — Steam 页面展示游戏资料
- 📚 **读书笔记** — 豆瓣页面展示阅读记录
- 📚 **读书笔记** — 豆瓣 / 微信读书页面展示阅读记录
- 💭 **碎碎念** — 瞬间页面记录日常灵感
## 下一步
docs/index.md
+1 -1
View File
@@ -26,7 +26,7 @@ features:
- title: 📝 沉浸阅读
details: 文章目录侧边悬浮、阅读进度条、代码高亮、图片灯箱，打造专注的阅读体验
- title: 🔌 插件生态
details: 深度集成瞬间、图库、友情链接、朋友圈、豆瓣、装备、Steam 等插件页面
details: 深度集成瞬间、图库、友情链接、订阅动态、豆瓣、装备、Steam 等插件页面
- title: ⚙️ 灵活配置
details: 丰富的主题设置面板，涵盖样式、导航、首页、文章、评论等全维度自定义
---
docs/pages/custom-page.md
+30 -13
View File
@@ -1,32 +1,49 @@
# 自定义页面
自定义页面是 Halo 的独立页面功能，用于创建关于、友链等独立内容页面。
自定义页面是 Halo 的独立页面功能，用于创建关于、留言板、订阅动态、微信读书等独立内容页面。
## 使用方式
1. 进入 Halo 后台 → **页面** → **新建**
2. 填写页面标题和内容
3. 可选择自定义模板
4. 发布页面
3. 可选：在「自定义模板」中选择主题提供的模板
4. 发布页面，并把页面加入导航菜单
页面地址由创建时设定的 slug 决定，主题不为自定义模板提供固定路由。
## 页面模板
主题提供以下自定义页面模板：
`theme.yaml` 中注册了 3 个自定义模板，加上默认的 `page.html` 共 4 种：
| 模板 | 文件 | 说明 |
|------|------|------|
| 默认 | page.html | 标准内容页面 |
| 留言板 | page_messageboard.html | 带评论的留言板页面 |
| 模板 | 模板文件 | 说明 |
|------|---------|------|
| 默认 | `page.html` | 标准内容页面 |
| 留言板（MessageBoard） | `page_messageboard.html` | 带评论的留言墙，标题与副标题可配置 |
| 订阅（Subscriptions） | `page_subscriptions.html` | 博友文章订阅动态，依赖官方「链接管理」插件的 RSS 订阅 |
| 微信读书（WeRead） | `weread.html` | 微信读书书架，依赖微信读书插件，访客免登录查看 |
### 留言板模板
选择留言板模板后，页面会自动集成评论组件，访客可以直接留言。标题和副标题使用主题设置中的配置。
选择留言板模板后，页面会集成评论组件，访客可以直接留言。标题和副标题在
**主题设置 → 留言板** 中配置，详见[留言板配置](/config/messageboard)。
使用步骤：
### 订阅模板
1. 新建页面，选择自定义模板为「留言板」
2. 在主题设置 → 留言板中配置标题和副标题
3. 发布页面，添加到导航菜单
feed / RSS 聚合不再依赖已停止提供的「朋友圈」插件，而由官方
「链接管理」（PluginLinks）插件的订阅能力提供。使用步骤：
1. 安装并启用[链接管理插件](https://www.halo.run/store/apps/app-hfbQg)，维护博友链接的 RSS 订阅源
2. 新建页面，自定义模板选择「订阅」
3. 在**主题设置 → 订阅**中调整每页条数、加载方式与布局，详见[订阅配置](/config/subscriptions)
未安装插件或暂无订阅动态时页面会显示友好提示，不会报错。
完整说明见[订阅页面](/pages/subscriptions)。
### 微信读书模板
选择「微信读书」模板后展示书架与阅读记录，标题 / 副标题在
**主题设置 → 微信读书** 中配置，详见[微信读书配置](/config/weread)。
该页面依赖 Halo 2.27+ 的能力。
## 页面功能
docs/pages/extended.md
+25 -20
View File
@@ -6,31 +6,37 @@ WarmIsland 主题深度集成了多款 Halo 插件，提供了丰富的扩展页
| 页面 | 所需插件 | 路由 |
|------|----------|------|
| 瞬间 | [PluginMoments](https://www.halo.run/store/apps/app-SnwWD) | /moments |
| 图库 | [PluginPhotos](https://www.halo.run/store/apps/app-BmQJW) | /photos |
| 友情链接 | [PluginLinks](https://www.halo.run/store/apps/app-hfbQg) | /links |
| 朋友圈 | [plugin-friends](https://www.halo.run/store/apps/app-yISsV) | /friends |
| 豆瓣 | [plugin-douban](https://www.halo.run/store/apps/app-srBOL) | /douban |
| 装备 | [equipment](https://www.halo.run/store/apps/app-ytygyqml) | /equipments |
| 足迹 | [footprint](https://www.halo.run/store/apps/app-XCtAQ) | /footprints |
| Steam | [steam](https://www.halo.run/store/apps/app-0ojqyzfh) | /steam |
| 记得 | [plugin-important-dates](https://github.com/yyliucha/plugin-important-dates) | /important-dates |
| 瞬间 | [PluginMoments](https://www.halo.run/store/apps/app-SnwWD) | `/moments` |
| 图库 | [PluginPhotos](https://www.halo.run/store/apps/app-BmQJW) | `/photos` |
| 友情链接 | [PluginLinks](https://www.halo.run/store/apps/app-hfbQg) | `/links` |
| 订阅动态 | [PluginLinks](https://www.halo.run/store/apps/app-hfbQg)（RSS 订阅） | 自定义页面，无固定路由 |
| 豆瓣 | [plugin-douban](https://www.halo.run/store/apps/app-srBOL) | `/douban` |
| 装备 | [equipment](https://www.halo.run/store/apps/app-ytygyqml) | `/equipments` |
| Steam | [steam](https://www.halo.run/store/apps/app-0ojqyzfh) | `/steam` |
| 记得 | [plugin-important-dates](https://github.com/yyliucha/plugin-important-dates) | `/important-dates` |
> 「朋友圈」（`plugin-friends`）插件已不再提供，其 feed / RSS 聚合能力由官方「链接管理」插件的订阅取代。
> 主题保留的 `friends.html` 仅供旧站点兼容，新站点请使用订阅模板，详见[订阅页面](/pages/subscriptions)。
## 订阅页面
订阅页面依赖官方「链接管理」插件的 RSS 订阅，展示博友们的最新文章，
支持分页 / 下滑加载与列表 / 网格布局。它属于自定义页面模板，地址由你创建页面时的 slug 决定。
使用前请在 Halo 后台 → 页面 → 新建 → 自定义模板中选择「订阅」。
详见[订阅页面](/pages/subscriptions)与[订阅配置](/config/subscriptions)。
## 豆瓣页面
[豆瓣插件](https://www.halo.run/store/apps/app-srBOL)
展示豆瓣观影/读书/音乐记录，支持按类型和状态筛选。
[豆瓣插件](https://www.halo.run/store/apps/app-srBOL)展示豆瓣观影/读书/音乐记录，支持按类型和状态筛选。
## 装备页面
[装备管理插件](https://www.halo.run/store/apps/app-ytygyqml)
展示个人装备清单，按分组分类展示。
## 足迹页面
[足迹插件](https://www.halo.run/store/apps/app-XCtAQ)
展示个人足迹地图。
[装备管理插件](https://www.halo.run/store/apps/app-ytygyqml)展示个人装备清单，按分组分类展示。
## Steam 页面
[Steam](https://www.halo.run/store/apps/app-0ojqyzfh)
展示 Steam 游戏资料，包括：
[Steam](https://www.halo.run/store/apps/app-0ojqyzfh)展示 Steam 游戏资料，包括：
- 玩家头像和昵称
- 游戏统计
@@ -39,8 +45,7 @@ WarmIsland 主题深度集成了多款 Halo 插件，提供了丰富的扩展页
## 记得页面
[记得插件](https://github.com/yyliucha/plugin-important-dates)
记录重要的日子、牵挂的人与座驾，「生活 / 爱车」双视图展示：
[记得插件](https://github.com/yyliucha/plugin-important-dates)记录重要的日子、牵挂的人与座驾，「生活 / 爱车」双视图展示：
- 重要日期（含农历）与倒计时便签
- 牵挂的人：大头贴、昵称、关系与生日倒计时
docs/pages/friends.md
-25
View File
@@ -1,25 +0,0 @@
# 朋友圈
朋友圈页面展示订阅的友站最新文章动态，需要安装 [朋友圈插件](https://www.halo.run/store/apps/app-yISsV)。
## 功能说明
页面以时间线形式展示友站更新，每条动态包含：
- 友站名称和头像
- 文章标题和链接
- 发布时间
## 使用方式
1. 在 Halo 后台安装并启用朋友圈插件
2. 在插件设置中添加友站 RSS 订阅源
3. 主题自动读取并展示友站动态
::: tip
朋友圈插件负责数据抓取，主题负责前端展示。如需调整抓取频率或内容，请在插件设置中操作。
:::
## 相关配置
- [朋友圈配置](/config/friends) — 页面标题
docs/pages/home.md
+1 -1
View File
@@ -16,7 +16,7 @@ Hero 区域占据整个视口高度，包含：
- **主标题**：默认使用站点标题，可在主题设置中自定义
- **副标题**：默认使用站点副标题
- **描述文案**：默认「无」（不显示、零请求）；可选「一言」（自动填入 `https://v1.hitokoto.cn/`，清空则用内置本地句子库）或「自定义」静态文案
- **描述文案**：默认「无」（不显示、零请求）；可选「一言」（API 字段默认预填 `https://v1.hitokoto.cn/`，清空则用内置本地句子库）或「自定义」静态文案
- **视觉效果**：渐变背景 + 呼吸光球 + 滚动模糊
页面滚动时，Hero 区域会产生模糊效果，内容向上淡出，底部有向下箭头提示滚动。
docs/pages/links.md
+2
View File
@@ -29,3 +29,5 @@
## 相关配置
- [友情链接配置](/config/links) — 展示样式
- [订阅配置](/config/subscriptions) — 同一插件提供的 RSS 订阅动态
- [订阅页面](/pages/subscriptions) — 博友文章动态页面
docs/pages/subscriptions.md
+53
View File
@@ -0,0 +1,53 @@
# 订阅页面
订阅页面按时间倒序展示博友们的最新文章，即原先「朋友圈 / feed 聚合」所提供的能力。
现在它由 **Halo 官方「链接管理」（PluginLinks）插件的 RSS 订阅**驱动，主题提供
`page_subscriptions.html` 自定义模板负责前端展示。
## 使用方式
1. 安装并启用 [链接管理插件](https://www.halo.run/store/apps/app-hfbQg)，在插件中维护博友链接的 RSS 订阅源
2. 进入 Halo 后台 → **页面** → **新建**
3. 选择自定义模板「**订阅**」（`Subscriptions`，对应 `page_subscriptions.html`）
4. 发布页面，并按需加入导航菜单
> 页面地址由你创建页面时设定的 slug 决定，主题**不提供固定的 `/subscriptions` 路由**；
> 只有插件提供的扩展页面（如 `/links`、`/moments`）才是固定路由。
## 页面内容
每条订阅动态是一张卡片，包含：
- 作者头像（缺失时显示首字占位）、作者名称与主页链接
- 发布日期
- 文章标题（点击跳转原文）、摘要
- 空数据时的友好提示，以及未安装链接管理插件时的安装引导
标题与作者链接均使用 `target="_blank"` + `rel="noopener noreferrer"`，
主题本身不会向第三方发起请求。
## 展示与加载
在[订阅配置](/config/subscriptions)中可调：
| 能力 | 可选值 |
| --- | --- |
| 布局 | 单列列表卡片 / 网格卡片（窄屏自动收敛列数） |
| 加载方式 | 底部分页（较新 / 较旧）/ 下滑自动加载 |
| 每页条数 | 1–100，默认 20 |
| 标题与副标题 | 自定义文本 |
## 从「朋友圈」迁移
`plugin-friends`（朋友圈）插件已不再提供，原来的 `/friends` 页面与「朋友圈」设置分组
仅作为旧站点兼容保留，模板检测到插件不可用时会显示空状态。迁移步骤：
1. 安装 / 启用「链接管理」插件，把原本在朋友圈插件里维护的 RSS 订阅源迁到链接管理插件的订阅中
2. 新建一个页面并选择「订阅」自定义模板
3. 确认动态正常展示后，删除旧的 `/friends` 页面与菜单项
## 相关配置
- [订阅配置](/config/subscriptions) — 全部 5 个设置项
- [友情链接页面](/pages/links) — 同一插件的友链展示
- [扩展页面](/pages/extended) — 插件前台页面一览