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

- 文档对齐 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

No files matched your search

+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
这是站点管理员主动开启的可选能力。把描述文案来源改回「无」、或清空该字段即可随时停止外部请求,无需重装主题。