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
1 parent
c92429d139
commit
5c7c6325b1
34 files changed
+500
-210
No files matched your search
@@ -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 聚合动态设置
|
||||
+29
-14
@@ -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 页面展示游戏资料
|
||||
- 📚 **读书笔记** — 豆瓣页面展示阅读记录
|
||||
- 📚 **读书笔记** — 豆瓣 / 微信读书页面展示阅读记录
|
||||
- 💭 **碎碎念** — 瞬间页面记录日常灵感
|
||||
|
||||
## 下一步
|
||||
|
||||
Reference in new issue
Block a user