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/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) — 插件前台页面一览