update README.md

docs/config/article.md

@@ -0,0 +1,131 @@
+# 文章
+
+文章配置控制文章详情页的展示方式，包括封面图、元信息、目录导航、代码高亮等功能。这些设置影响每一篇文章的阅读体验。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `article_show_cover` | 开关 | `true` | 显示封面图 |
+| `article_show_date` | 开关 | `true` | 显示发布日期 |
+| `article_show_category` | 开关 | `true` | 显示分类 |
+| `article_show_tags` | 开关 | `true` | 显示标签 |
+| `article_show_nav` | 开关 | `true` | 显示上下篇导航 |
+| `article_show_toc` | 开关 | `true` | 显示文章目录 |
+| `article_toc_position` | 下拉 | `left` | 目录位置：`left` / `right` |
+| `article_show_word_count` | 开关 | `true` | 显示字数统计 |
+| `article_show_visit_count` | 开关 | `true` | 显示阅读量统计 |
+| `article_show_read_time` | 开关 | `false` | 显示预计阅读时间 |
+| `article_code_theme` | 下拉 | `warm` | 代码高亮主题：`warm` / `cold` |
+
+## 详细说明
+
+### 封面图（article_show_cover）
+
+开启后，文章详情页顶部会显示封面图（全宽展示）。封面图来自 Halo 后台编辑文章时设置的「封面图」字段。
+
+::: tip
+如果文章未设置封面图，即使开启此选项也不会显示任何内容，页面会自动调整布局。建议为重要文章设置封面图以获得最佳视觉效果。
+:::
+
+### 元信息展示
+
+以下开关控制文章标题下方的元信息区域：
+
+| 配置项 | 说明 |
+| --- | --- |
+| `article_show_date` | 显示文章发布日期 |
+| `article_show_category` | 显示文章所属分类（可点击跳转） |
+| `article_show_tags` | 显示文章标签列表（可点击跳转） |
+| `article_show_word_count` | 显示文章字数统计 |
+| `article_show_visit_count` | 显示文章阅读量 |
+| `article_show_read_time` | 显示预计阅读时间（默认关闭） |
+
+::: tip
+预计阅读时间基于中文约 300 字/分钟、英文约 200 词/分钟的阅读速度估算。如需开启，建议同时开启字数统计，两者配合提供完整的阅读参考信息。
+:::
+
+### 上下篇导航（article_show_nav）
+
+开启后，文章底部会显示「上一篇」和「下一篇文章」的导航链接，方便访客连续阅读。
+
+### 文章目录（article_show_toc）
+
+开启后，文章页面会显示基于标题层级自动生成的目录（Table of Contents），帮助读者快速定位和跳转到文章各章节。
+
+#### 目录位置（article_toc_position）
+
+| 值 | 说明 |
+| --- | --- |
+| `left` | 目录显示在正文左侧（默认） |
+| `right` | 目录显示在正文右侧 |
+
+#### 桌面端行为
+
+- 目录以侧边栏形式固定显示
+- 滚动时自动高亮当前阅读位置对应的目录项
+- 点击目录项平滑滚动到对应章节
+- 当文章标题较少（少于 2 个）时，目录区域自动隐藏
+
+#### 移动端行为
+
+- 目录不显示侧边栏，而是在文章标题下方显示一个可展开的目录按钮
+- 点击按钮弹出目录面板，选择后自动关闭
+- 这种设计避免了移动端屏幕空间不足的问题
+
+::: tip
+目录仅提取文章中的 `<h2>` 和 `<h3>` 标签生成。建议在撰写长文时合理使用二级和三级标题，以获得结构清晰的目录。
+:::
+
+### 代码高亮主题（article_code_theme）
+
+WarmIsland 使用 Prism.js 实现代码语法高亮，提供两种主题风格：
+
+| 值 | 说明 |
+| --- | --- |
+| `warm` | 暖色调代码主题，与暖屿整体风格一致（默认） |
+| `cold` | 冷色调代码主题，类似经典代码编辑器风格，适合技术博客 |
+
+```yaml
+# 技术博客推荐
+article_code_theme: cold
+
+# 生活博客推荐
+article_code_theme: warm
+```
+
+::: tip
+代码高亮支持多种编程语言，包括 JavaScript、Python、Java、Go、Rust、YAML、JSON、Bash 等。语言检测基于代码块的语言标记自动完成。
+:::
+
+## 阅读增强功能
+
+除了可配置的项目外，文章详情页还包含以下内置功能：
+
+### 阅读进度条
+
+页面顶部显示一条阅读进度条，随滚动位置实时更新，让读者直观了解当前阅读进度。进度条颜色跟随强调色。
+
+### 点赞按钮
+
+文章底部提供点赞按钮，访客可以点击表达对文章的喜爱。点赞数据由 Halo 核心功能提供。
+
+### LightGallery 图片灯箱
+
+文章中的图片支持点击放大查看，基于 LightGallery 实现：
+
+- 点击图片弹出灯箱查看大图
+- 支持左右切换浏览多张图片
+- 支持缩放、旋转等操作
+- 按 `Esc` 或点击背景关闭灯箱
+
+::: tip
+LightGallery 会自动识别文章正文中的所有 `<img>` 标签并应用灯箱效果，无需手动配置。
+:::
+
+## 相关页面
+
+- [首页](/config/home) — 首页文章列表配置
+- [评论](/config/comment) — 文章评论样式配置
+- [样式设置](/config/style) — 强调色与圆角配置
+- [文章详情页](/pages/post) — 文章模板与结构说明

docs/config/basic.md

@@ -0,0 +1,80 @@
+# 基础设置
+
+基础设置是 WarmIsland 主题的核心配置区域，用于定义站点的基本信息和全局标签文案。这些配置项会影响导航栏、页脚、SEO 以及全站多处显示内容。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `owner_name` | 文本 | — | 站点名称，显示在导航栏、页脚等位置 |
+| `site_description` | 多行文本 | — | 站点描述，用于 SEO meta 信息 |
+| `logo` | 附件 | — | 自定义 Logo 图片 |
+| `favicon` | 附件 | — | 自定义 Favicon 图标 |
+| `label_search` | 文本 | `搜索` | 搜索按钮的标签文案 |
+| `label_theme_switch` | 文本 | `切换主题` | 主题切换按钮的标签文案 |
+| `label_archives_title` | 文本 | `归档` | 归档页面的标题文案 |
+
+## 详细说明
+
+### 站点名称（owner_name）
+
+填写你的站点名称，该名称会出现在以下位置：
+
+- 导航栏左侧（未设置 Logo 时作为文字 Logo 显示）
+- 页脚版权信息区域
+- 浏览器标签页标题（结合文章标题）
+
+::: tip
+如果未设置 `owner_name`，主题会尝试读取 Halo 后台的站点标题作为回退值。建议始终显式设置此项以确保显示一致。
+:::
+
+### 站点描述（site_description）
+
+站点描述用于生成 HTML `<meta name="description">` 标签，对搜索引擎优化（SEO）至关重要。建议控制在 80–160 个字符之间，简洁地概括站点内容与定位。
+
+```yaml
+# 示例
+site_description: "一个关于技术、生活与思考的个人博客，记录温暖与灵感。"
+```
+
+### 自定义 Logo（logo）
+
+上传自定义 Logo 图片，支持 PNG、SVG、JPG 等常见格式。设置后，Logo 将替代站点名称显示在导航栏左侧。
+
+::: tip
+推荐使用 SVG 格式的 Logo，在任何分辨率下都能保持清晰。建议 Logo 高度不超过 40px，宽度按比例缩放。
+:::
+
+### 自定义 Favicon（favicon）
+
+Favicon 是显示在浏览器标签页上的小图标。上传一个正方形图标（推荐 32×32 或 64×64 像素的 PNG/ICO 格式）。
+
+::: warning
+部分浏览器对 Favicon 有缓存机制，更换后可能需要清除浏览器缓存或使用无痕模式查看效果。
+:::
+
+### 标签文案自定义
+
+WarmIsland 主题允许你自定义界面中出现的标签文案，方便进行多语言适配或个性化表达：
+
+- **`label_search`** — 导航栏搜索按钮的显示文字，默认为「搜索」
+- **`label_theme_switch`** — 导航栏主题切换按钮的显示文字，默认为「切换主题」
+- **`label_archives_title`** — 归档页面的标题，默认为「归档」
+
+```yaml
+# 英文站点示例
+label_search: "Search"
+label_theme_switch: "Switch Theme"
+label_archives_title: "Archives"
+```
+
+::: tip
+标签文案的修改会即时生效，无需重启 Halo。如果使用多语言场景，可以配合 Halo 的多语言插件实现更完整的国际化。
+:::
+
+## 相关页面
+
+- [样式设置](/config/style) — 调整配色、圆角、动画等视觉表现
+- [导航栏](/config/navbar) — 配置导航栏样式与功能按钮
+- [页脚](/config/footer) — 配置页脚版权信息与社交链接
+- [快速开始](/guide/getting-started) — 主题安装与初始配置指南

docs/config/comment.md

@@ -0,0 +1,75 @@
+# 评论
+
+评论配置控制全站评论区域的外观样式，影响文章详情页、留言板等所有包含评论组件的页面。WarmIsland 基于 Halo 的 `halo:comment` 组件提供评论功能，并提供了样式定制选项。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `comment_style` | 下拉 | `warm` | 评论样式：`warm` / `minimal` |
+| `comment_show_avatar` | 开关 | `true` | 显示头像 |
+
+## 详细说明
+
+### 评论样式（comment_style）
+
+| 值 | 说明 |
+| --- | --- |
+| `warm` | 暖色风格，与暖屿主题整体风格一致，圆角卡片、柔和配色（默认） |
+| `minimal` | 极简风格，去除装饰性元素，线条简洁，适合内容导向型站点 |
+
+::: tip
+`warm` 样式与暖屿的整体设计语言最为协调，推荐大多数用户使用。`minimal` 样式适合希望让评论区域更低调、不抢夺正文注意力的场景。
+:::
+
+### 显示头像（comment_show_avatar）
+
+开启后，每条评论左侧会显示评论者的头像。关闭后，评论以纯文本形式排列，节省空间。
+
+::: tip
+如果站点评论以匿名或短评为主，可以考虑关闭头像以获得更紧凑的布局。如果评论互动较多，建议保持开启以增强社交感。
+:::
+
+## 评论功能说明
+
+WarmIsland 的评论系统基于 Halo 的 `halo:comment` 组件实现，提供以下核心功能：
+
+### 回复
+
+支持多级嵌套回复，访客可以针对特定评论进行回复，形成讨论线程。
+
+### 点赞
+
+每条评论支持点赞功能，访客可以表达对评论的认同。
+
+### Markdown 支持
+
+评论内容支持 Markdown 基础语法，包括：
+
+- **粗体** 和 *斜体*
+- 代码（行内 `` `code` `` 和代码块）
+- 链接
+- 列表
+
+::: warning
+为安全起见，评论中的 Markdown 支持是受限的，不支持 HTML 标签注入、JavaScript 执行等危险操作。
+:::
+
+### 评论管理
+
+评论数据通过 Halo 后台统一管理：
+
+1. 登录 Halo 后台管理控制台
+2. 进入 **评论** 管理页面
+3. 可以查看、审核、回复和删除评论
+4. 支持设置评论审核规则（如需审核后发布）
+
+::: tip
+建议开启评论审核功能以防止垃圾评论。可以在 Halo 后台 → **设置** → **评论** 中配置评论审核策略。
+:::
+
+## 相关页面
+
+- [留言板](/config/messageboard) — 留言板页面配置
+- [文章](/config/article) — 文章详情页配置
+- [样式设置](/config/style) — 全局样式与配色配置

docs/config/footer.md

@@ -0,0 +1,166 @@
+# 页脚
+
+页脚是站点全局可见的底部区域，用于展示版权信息、备案号、社交链接以及自定义 HTML 内容。WarmIsland 提供了灵活的页脚配置，满足法律合规、社交推广和数据分析等多种需求。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `footer_copyright` | 文本 | — | 版权信息（留空则使用默认格式 © 年份 站点标题） |
+| `footer_icp` | 文本 | — | ICP 备案号 |
+| `footer_socials` | 重复器 | — | 社交链接（平台名称 / 图标类名 / 链接地址） |
+| `footer_show_powered` | 开关 | `true` | 显示「Powered by Halo」 |
+| `footer_show_theme` | 开关 | `true` | 显示主题版本 |
+| `footer_custom_html` | 代码 | — | 自定义 HTML（统计代码等） |
+
+## 详细说明
+
+### 版权信息（footer_copyright）
+
+自定义页脚版权信息文本。留空时，主题会自动生成默认格式的版权信息：`© 当前年份 站点标题`。
+
+```yaml
+# 自定义版权信息
+footer_copyright: "© 2024 暖屿 All Rights Reserved"
+
+# 留空使用默认格式
+footer_copyright: ""
+# 自动生成：© 2026 暖屿
+```
+
+::: tip
+如果需要更复杂的版权信息（如包含链接），可以使用 `footer_custom_html` 配置项通过 HTML 实现。
+:::
+
+### ICP 备案号（footer_icp）
+
+填写你的 ICP 备案号，显示在页脚版权信息下方。如果站点部署在中国大陆的服务器上，根据法规要求需要展示备案号。
+
+```yaml
+footer_icp: "京ICP备12345678号-1"
+```
+
+::: warning
+ICP 备案号通常需要链接到工信部的备案查询页面。主题会自动为备案号添加指向 `https://beian.miit.gov.cn/` 的链接。
+:::
+
+### 社交链接（footer_socials）
+
+通过重复器（Repeater）添加多个社交链接，每条链接包含三个字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `platform` | 平台名称，如 GitHub、微博、Twitter 等 |
+| `icon` | 图标类名，使用 Font Awesome 图标类名 |
+| `url` | 链接地址 |
+
+#### Font Awesome 图标类名示例
+
+社交链接的图标使用 Font Awesome 图标库，以下是常用平台的图标类名：
+
+| 平台 | 图标类名 |
+| --- | --- |
+| GitHub | `fa-brands fa-github` |
+| 微博 | `fa-brands fa-weibo` |
+| Twitter / X | `fa-brands fa-x-twitter` |
+| 微信 | `fa-brands fa-weixin` |
+| Bilibili | `fa-brands fa-bilibili` |
+| 知乎 | `fa-brands fa-zhihu` |
+| 邮箱 | `fa-solid fa-envelope` |
+| RSS | `fa-solid fa-rss` |
+| 抖音 | `fa-brands fa-tiktok` |
+| 小红书 | `fa-solid fa-book-open` |
+| Telegram | `fa-brands fa-telegram` |
+| Discord | `fa-brands fa-discord` |
+| YouTube | `fa-brands fa-youtube` |
+| Spotify | `fa-brands fa-spotify` |
+
+```yaml
+# 社交链接配置示例
+footer_socials:
+  - platform: GitHub
+    icon: fa-brands fa-github
+    url: https://github.com/your-username
+  - platform: 微博
+    icon: fa-brands fa-weibo
+    url: https://weibo.com/your-username
+  - platform: 邮箱
+    icon: fa-solid fa-envelope
+    url: mailto:your@email.com
+  - platform: RSS
+    icon: fa-solid fa-rss
+    url: /rss.xml
+```
+
+::: tip
+你可以在 [Font Awesome 官网](https://fontawesome.com/icons) 搜索更多图标。WarmIsland 主题内置了 Font Awesome 图标库，无需额外引入。
+:::
+
+### 显示「Powered by Halo」（footer_show_powered）
+
+开启后，页脚会显示「Powered by Halo」文字，链接到 Halo 官网。这是对 Halo 开源项目的支持与致谢。
+
+### 显示主题版本（footer_show_theme）
+
+开启后，页脚会显示当前 WarmIsland 主题的名称和版本号，如「Theme WarmIsland v1.0.0」。
+
+::: tip
+保持开启主题版本显示有助于访客了解你使用的主题，也可能帮助你在遇到问题时快速确认当前版本号。
+:::
+
+### 自定义 HTML（footer_custom_html）
+
+在此处编写自定义 HTML 代码，会注入到页脚区域的末尾。最常见的用途是添加网站统计代码。
+
+```html
+<!-- 百度统计 -->
+<script>
+var _hmt = _hmt || [];
+(function() {
+  var hm = document.createElement("script");
+  hm.src = "https://hm.baidu.com/hm.js?your-site-id";
+  var s = document.getElementsByTagName("script")[0];
+  s.parentNode.insertBefore(hm, s);
+})();
+</script>
+
+<!-- Google Analytics -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'G-XXXXXXXXXX');
+</script>
+
+<!-- 自定义页脚内容 -->
+<p style="text-align:center;margin-top:1rem;">
+  Made with ❤️ by WarmIsland
+</p>
+```
+
+::: warning
+自定义 HTML 会直接注入到页面中，请确保代码安全可靠。不要在此处添加可能影响页面性能或安全性的代码。统计代码建议放置在 `<script>` 标签中，并使用 `async` 属性以避免阻塞页面渲染。
+:::
+
+## 页脚布局
+
+页脚区域从上到下依次为：
+
+```
+┌─────────────────────────────────────┐
+│         社交链接图标区域              │  ← footer_socials
+├─────────────────────────────────────┤
+│  © 2026 暖屿  |  京ICP备xxxxx号     │  ← 版权信息 + 备案号
+├─────────────────────────────────────┤
+│  Powered by Halo  |  Theme 暖屿     │  ← 可选的引擎与主题信息
+├─────────────────────────────────────┤
+│         自定义 HTML 区域             │  ← footer_custom_html
+└─────────────────────────────────────┘
+```
+
+## 相关页面
+
+- [基础设置](/config/basic) — 站点名称配置
+- [导航栏](/config/navbar) — 导航栏配置
+- [样式设置](/config/style) — 强调色与圆角配置

docs/config/friends.md

@@ -0,0 +1,65 @@
+# 朋友圈
+
+朋友圈模块用于聚合展示你订阅的站点最新动态，类似于 RSS 阅读器的社交化呈现。访客可以在你的站点上浏览友站最新文章，发现更多优质内容。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `friends_page_title` | 文本 | `朋友圈` | 页面标题 |
+
+## 前置依赖
+
+::: danger
+朋友圈功能依赖 Halo 的 **plugin-friends** 插件。如果未安装此插件，朋友圈页面将无法正常工作。
+
+安装方式：Halo 后台 → **插件** → **安装** → 搜索「Friends」或从 [GitHub Releases](https://github.com/halo-sigs/plugin-friends) 下载安装。
+:::
+
+## 详细说明
+
+### 页面标题（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. 进入 **朋友圈** 或 **Friends** 管理页面
+3. 点击 **添加订阅** 填写：
+   - **站点名称** — 友站名称
+   - **RSS 地址** — 友站的 RSS/Atom 订阅地址
+   - **Logo** — 友站 Logo（可选）
+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

@@ -0,0 +1,137 @@
+# Hero 首屏
+
+Hero 首屏是 WarmIsland 主题的标志性区域，占据首页首屏的全部视口高度，以渐变背景、呼吸光球和动态文案营造沉浸式的第一印象。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `hero_enabled` | 开关 | `true` | 启用 Hero 模块 |
+| `hero_title` | 文本 | — | 主标题（留空则使用站点标题） |
+| `hero_subtitle` | 文本 | — | 副标题（留空则使用站点副标题） |
+| `hero_description_mode` | 下拉 | `hitokoto` | 描述文案来源：`none` / `hitokoto` / `custom` |
+| `hero_hitokoto_api` | URL | `https://v1.hitokoto.cn/` | 一言 API 地址 |
+| `hero_hitokoto_categories` | 多选 | `d, i, k` | 一言句子类型 |
+| `hero_custom_description` | 多行文本 | — | 自定义描述文案 |
+| `hero_background_image` | 附件 | — | 背景图片 |
+
+## 详细说明
+
+### 启用 Hero 模块（hero_enabled）
+
+关闭后，首页将不再显示 Hero 区域，直接展示文章列表。适合内容导向型站点或不需要首屏视觉冲击的场景。
+
+### 主标题与副标题
+
+- **`hero_title`** — Hero 区域的主标题，字体最大、最醒目。留空时自动使用 [基础设置](/config/basic) 中的 `owner_name` 作为回退。
+- **`hero_subtitle`** — 主标题下方的副标题，字号较小。留空时自动使用 Halo 后台设置的站点副标题。
+
+```yaml
+# 示例
+hero_title: "暖屿"
+hero_subtitle: "记录温暖与灵感"
+```
+
+### 描述文案来源（hero_description_mode）
+
+控制 Hero 区域主标题下方显示的描述文案，提供三种模式：
+
+| 值 | 说明 |
+| --- | --- |
+| `none` | 不显示描述文案 |
+| `hitokoto` | 从一言 API 实时获取随机句子（默认） |
+| `custom` | 显示自定义的描述文案 |
+
+### 一言模式（hitokoto）
+
+选择 `hitokoto` 模式后，Hero 区域会从一言 API 获取随机句子，每次刷新页面都会展示不同的内容。
+
+#### 一言 API 地址（hero_hitokoto_api）
+
+默认使用官方 API `https://v1.hitokoto.cn/`。如果你部署了一言的私有实例，可以修改为自建 API 地址。
+
+::: tip
+自建一言 API 可以提升加载速度并避免第三方服务不稳定的问题。部署方式请参考 [hitokoto 官方文档](https://developer.hitokoto.cn/)。
+:::
+
+#### 一言句子类型（hero_hitokoto_categories）
+
+通过勾选来筛选获取的句子类型，支持多选：
+
+| 值 | 类型 | 说明 |
+| --- | --- | --- |
+| `a` | 动画 | 动画作品中的经典台词 |
+| `b` | 漫画 | 漫画作品中的句子 |
+| `c` | 游戏 | 游戏中的对白与文案 |
+| `d` | 文学 | 文学作品中的名句（默认选中） |
+| `e` | 原创 | 一言社区原创投稿 |
+| `f` | 来自网络 | 网络流传的金句 |
+| `g` | 其他 | 其他来源 |
+| `h` | 影视 | 影视剧中的台词 |
+| `i` | 诗词 | 古诗词名句（默认选中） |
+| `k` | 哲学 | 哲学思辨类句子（默认选中） |
+| `l` | 抖机灵 | 幽默风趣的句子 |
+
+默认选中 `d`（文学）、`i`（诗词）、`k`（哲学），与暖屿的文艺气质相契合。
+
+```yaml
+# 示例：只获取文学和诗词类句子
+hero_hitokoto_categories:
+  - d
+  - i
+```
+
+### 自定义模式（custom）
+
+选择 `custom` 模式后，需要在 `hero_custom_description` 中填写自定义的描述文案。此配置项仅在 `hero_description_mode` 为 `custom` 时显示。
+
+```yaml
+hero_description_mode: custom
+hero_custom_description: "用文字记录生活，用代码构建世界。"
+```
+
+::: tip
+自定义描述支持多行文本，但建议控制在 1–2 行以内，过长的文案在移动端可能需要滚动才能完整显示。
+:::
+
+### 背景图片（hero_background_image）
+
+上传自定义背景图片，将作为 Hero 区域的背景展示。未设置时，Hero 区域使用渐变色背景。
+
+::: warning
+背景图片会自动应用模糊和暗化处理，以确保前景文字的可读性。建议选择色彩柔和、不包含大量细节的图片作为背景，避免干扰文案阅读。
+:::
+
+## 视觉效果
+
+Hero 区域包含以下精心设计的视觉效果：
+
+### 渐变背景
+
+基于强调色生成的多层渐变背景，在浅色和深色模式下分别适配不同的色调。渐变方向从左上到右下，营造温暖的视觉基调。
+
+### 呼吸光球
+
+多个半透明的光球在背景中缓慢浮动和脉动，产生「呼吸」般的节奏感。此效果可通过 [样式设置](/config/style) 中的 `animation_breath` 开关控制。
+
+### 滚动模糊
+
+当页面向下滚动时，Hero 区域会逐渐应用高斯模糊效果，使焦点自然过渡到下方的内容区域。
+
+### 内容淡出
+
+随着滚动距离增加，Hero 区域内的标题、副标题和描述文案会逐渐淡出并上移，形成视差效果。
+
+### 滚动指示器
+
+Hero 区域底部有一个向下滚动的指示动画（小箭头 + 弹跳动画），引导访客继续浏览下方内容。
+
+::: tip
+以上所有视觉效果均通过 CSS 和少量 JavaScript 实现，对性能影响极小。如果需要禁用动画效果，可在 [样式设置](/config/style) 中关闭对应的动画开关。
+:::
+
+## 相关页面
+
+- [首页](/config/home) — 首页文章列表配置
+- [样式设置](/config/style) — 动画效果与配色配置
+- [基础设置](/config/basic) — 站点名称与描述配置

docs/config/home.md

@@ -0,0 +1,163 @@
+# 首页
+
+首页是访客进入站点后看到的第一个内容页面（Hero 区域下方），以文章卡片列表为核心展示形式。WarmIsland 提供了丰富的首页配置选项，涵盖卡片信息展示、摘要行数、加载方式以及各种文案自定义。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `home_pinned_title` | 文本 | `置顶` | 置顶模块标题 |
+| `home_posts_title` | 文本 | `文章` | 文章模块标题 |
+| `home_card_show_visit` | 开关 | `true` | 文章卡片显示阅读量 |
+| `home_card_show_wordcount` | 开关 | `true` | 文章卡片显示字数 |
+| `home_card_show_category` | 开关 | `true` | 文章卡片显示分类 |
+| `home_card_show_tags` | 开关 | `true` | 文章卡片显示标签 |
+| `home_excerpt_lines` | 数字 | `3` | 文章简介显示行数 |
+| `home_post_loading` | 下拉 | `pagination` | 文章加载方式：`pagination` / `infinite_scroll` |
+| `home_label_newer` | 文本 | `较新` | 分页-较新标签 |
+| `home_label_older` | 文本 | `较旧` | 分页-较旧标签 |
+| `home_label_loading` | 文本 | `加载中...` | 无限滚动-加载中文案 |
+| `home_label_all_loaded` | 文本 | `已加载全部文章` | 无限滚动-全部加载文案 |
+| `home_label_no_posts` | 文本 | `暂无文章。` | 暂无文章文案 |
+| `home_label_post_count` | 文本 | `共 {total} 篇文章` | 文章数量文案（`{total}` 为占位符） |
+
+## 详细说明
+
+### 模块标题
+
+首页文章列表分为两个模块区域，各自拥有独立的标题：
+
+- **`home_pinned_title`** — 置顶文章区域的标题，默认为「置顶」。只有存在置顶文章时此区域才会显示。
+- **`home_posts_title`** — 普通文章区域的标题，默认为「文章」。
+
+```yaml
+# 英文站点示例
+home_pinned_title: "Pinned"
+home_posts_title: "Posts"
+```
+
+::: tip
+置顶文章需要在 Halo 后台编辑文章时手动设置置顶属性。置顶文章会显示在列表最前方的独立区域中，与普通文章区域以标题分隔。
+:::
+
+### 文章卡片信息展示
+
+通过四个开关控制文章卡片上显示的元信息：
+
+| 配置项 | 说明 |
+| --- | --- |
+| `home_card_show_visit` | 显示文章阅读量（依赖 Halo 统计功能） |
+| `home_card_show_wordcount` | 显示文章字数统计 |
+| `home_card_show_category` | 显示文章所属分类 |
+| `home_card_show_tags` | 显示文章标签列表 |
+
+::: tip
+关闭不需要的元信息可以让卡片更简洁，在移动端尤其有效。建议至少保留分类或标签中的一项，帮助访客快速了解文章主题。
+:::
+
+### 文章简介显示行数（home_excerpt_lines）
+
+控制文章卡片中摘要文本的最大显示行数。超出部分会被截断并显示省略号。
+
+- 设为 `0` 时不显示摘要
+- 设为 `2`–`3` 适合紧凑布局
+- 设为 `4`–`5` 适合需要更多预览内容的场景
+
+```yaml
+home_excerpt_lines: 3  # 默认，显示 3 行摘要
+```
+
+::: warning
+此设置使用 CSS `-webkit-line-clamp` 实现多行截断，在所有现代浏览器中均可正常工作。摘要内容来自 Halo 后台文章编辑时的「摘要」字段，如未填写则自动从正文提取。
+:::
+
+### 文章加载方式（home_post_loading）
+
+| 值 | 说明 |
+| --- | --- |
+| `pagination` | 传统分页，页面底部显示「较新/较旧」导航按钮（默认） |
+| `infinite_scroll` | 无限滚动，滚动到底部自动加载下一页文章 |
+
+#### 分页模式文案
+
+选择 `pagination` 模式时，可自定义分页按钮的文案：
+
+- **`home_label_newer`** — 指向较新文章的按钮文案，默认「较新」
+- **`home_label_older`** — 指向较旧文章的按钮文案，默认「较旧」
+
+#### 无限滚动模式文案
+
+选择 `infinite_scroll` 模式时，可自定义加载状态的文案：
+
+- **`home_label_loading`** — 正在加载时的提示文案，默认「加载中...」
+- **`home_label_all_loaded`** — 所有文章加载完毕后的提示文案，默认「已加载全部文章」
+
+```yaml
+# 英文站点示例
+home_post_loading: pagination
+home_label_newer: "Newer"
+home_label_older: "Older"
+
+# 或使用无限滚动
+home_post_loading: infinite_scroll
+home_label_loading: "Loading..."
+home_label_all_loaded: "All posts loaded"
+```
+
+### 暂无文章文案（home_label_no_posts）
+
+当站点没有任何已发布文章时，首页文章区域显示的提示文案。
+
+### 文章数量文案（home_label_post_count）
+
+显示在文章列表上方的文章总数统计文案。`{total}` 是占位符，会被替换为实际的文章数量。
+
+```yaml
+# 默认
+home_label_post_count: "共 {total} 篇文章"
+# 显示效果：共 12 篇文章
+
+# 英文示例
+home_label_post_count: "{total} posts in total"
+# 显示效果：12 posts in total
+```
+
+::: tip
+`{total}` 占位符是必须的，如果文案中不包含此占位符，文章数量将无法正确显示。
+:::
+
+## 页面布局结构
+
+首页的整体布局从上到下依次为：
+
+```
+┌─────────────────────────────┐
+│         Hero 首屏区域        │  ← 可选，参见 Hero 配置
+├─────────────────────────────┤
+│     置顶模块标题（置顶）      │  ← home_pinned_title
+│  ┌─────┐ ┌─────┐ ┌─────┐   │
+│  │置顶1 │ │置顶2 │ │置顶3 │   │  ← 置顶文章卡片
+│  └─────┘ └─────┘ └─────┘   │
+├─────────────────────────────┤
+│     文章模块标题（文章）      │  ← home_posts_title
+│  ┌─────┐ ┌─────┐ ┌─────┐   │
+│  │文章1 │ │文章2 │ │文章3 │   │  ← 普通文章卡片
+│  └─────┘ └─────┘ └─────┘   │
+│  ┌─────┐ ┌─────┐ ┌─────┐   │
+│  │文章4 │ │文章5 │ │文章6 │   │
+│  └─────┘ └─────┘ └─────┘   │
+├─────────────────────────────┤
+│     较新 ← → 较旧           │  ← 分页导航（或无限滚动）
+└─────────────────────────────┘
+```
+
+::: tip
+文章卡片在桌面端以多列网格排列，在平板和移动端自动调整为单列或双列布局，确保在各种屏幕尺寸下的阅读体验。
+:::
+
+## 相关页面
+
+- [Hero 首屏](/config/hero) — Hero 区域配置
+- [文章](/config/article) — 文章详情页配置
+- [样式设置](/config/style) — 容器宽度与动画效果配置
+- [首页页面](/pages/home) — 首页模板与结构说明

docs/config/links.md

@@ -0,0 +1,70 @@
+# 友情链接
+
+友情链接模块用于展示与其他站点的互链关系，是博客社交属性的重要体现。WarmIsland 提供了三种展示样式，适配不同的视觉偏好。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `links_page_title` | 文本 | `友情链接` | 页面标题 |
+| `links_style` | 下拉 | `cards` | 展示样式：`grid` / `list` / `cards` |
+
+## 前置依赖
+
+::: danger
+友情链接功能依赖 Halo 的 **PluginLinks** 插件。如果未安装此插件，友情链接页面将无法正常工作。
+
+安装方式：Halo 后台 → **插件** → **安装** → 搜索「Links」→ 安装并启用。
+:::
+
+## 详细说明
+
+### 页面标题（links_page_title）
+
+友情链接页面的标题，显示在页面顶部。
+
+```yaml
+links_page_title: "友情链接"    # 默认
+links_page_title: "友链"        # 简称
+links_page_title: "Friends"     # 英文站点
+```
+
+### 展示样式（links_style）
+
+| 值 | 说明 |
+| --- | --- |
+| `grid` | 网格样式，友链以均匀的网格卡片排列，紧凑整齐 |
+| `list` | 列表样式，友链以水平列表项排列，信息展示更完整 |
+| `cards` | 卡片样式，友链以独立卡片展示，视觉层次丰富（默认） |
+
+::: tip
+`cards` 样式最为推荐，它在视觉效果和信息展示之间取得了最佳平衡。`grid` 样式适合友链数量较多的站点，`list` 样式适合需要展示详细描述信息的场景。
+:::
+
+## 链接管理
+
+友情链接的数据通过 Halo 后台管理，而非主题设置面板。管理步骤如下：
+
+1. 登录 Halo 后台管理控制台
+2. 进入 **链接** → **新建** 添加友情链接
+3. 填写链接信息：
+   - **名称** — 站点名称
+   - **URL** — 站点地址
+   - **Logo** — 站点 Logo 或头像
+   - **描述** — 站点简介
+   - **分组** — 链接分组（可选）
+4. 保存后，友情链接页面会自动展示
+
+::: tip
+建议为每个友链填写 Logo 和描述信息，这样在 `cards` 和 `grid` 样式下展示效果更佳。Logo 推荐使用正方形图片。
+:::
+
+### 分组管理
+
+PluginLinks 支持链接分组功能。你可以将友链按不同类别分组（如「技术博客」「生活博客」「工具站点」等），页面会以分组为单位展示。
+
+## 相关页面
+
+- [朋友圈](/config/friends) — 朋友圈页面配置
+- [页脚](/config/footer) — 页脚社交链接配置
+- [友情链接页面](/pages/links) — 友链模板与结构说明

docs/config/messageboard.md

@@ -0,0 +1,63 @@
+# 留言板
+
+留言板是 WarmIsland 主题提供的互动页面，访客可以在此留下评论和祝福。留言板基于 Halo 的评论系统实现，拥有独立的标题和副标题配置。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `messageboard_title` | 文本 | `留言板` | 留言板标题 |
+| `messageboard_subtitle` | 多行文本 | `在这里留下你的足迹吧 🌙` | 留言板副标题 |
+
+## 详细说明
+
+### 留言板标题（messageboard_title）
+
+留言板页面的主标题，显示在页面顶部最醒目的位置。
+
+```yaml
+messageboard_title: "留言板"        # 默认
+messageboard_title: "留言"          # 简称
+messageboard_title: "Guestbook"     # 英文站点
+```
+
+### 留言板副标题（messageboard_subtitle）
+
+标题下方的副标题，用于引导访客留言。默认为「在这里留下你的足迹吧 🌙」，支持 Emoji 和多行文本。
+
+```yaml
+messageboard_subtitle: "在这里留下你的足迹吧 🌙"    # 默认
+messageboard_subtitle: "说点什么吧 ✨"              # 替代方案
+messageboard_subtitle: "Leave a message 🌙"         # 英文站点
+```
+
+::: tip
+副标题是营造留言板氛围的重要元素，建议使用温暖、亲切的措辞，配合 Emoji 效果更佳。
+:::
+
+## 自定义模板使用步骤
+
+留言板页面需要通过 Halo 后台创建自定义页面来使用，具体步骤如下：
+
+1. 登录 Halo 后台管理控制台
+2. 进入 **页面** → **新建**
+3. 填写页面基本信息：
+   - **标题** — 建议与 `messageboard_title` 保持一致
+   - **别名** — 如 `messageboard` 或 `guestbook`
+4. 在页面模板选择中，选择 **留言板**（messageboard）模板
+5. 发布页面
+6. 将页面链接添加到导航菜单中
+
+::: warning
+如果未选择留言板模板，页面将使用默认模板渲染，不会显示留言板专属的标题、副标题和评论组件。请务必在创建页面时选择正确的模板。
+:::
+
+::: tip
+留言板的评论功能依赖 Halo 的评论系统。确保已在 Halo 后台 → **设置** → **评论** 中开启评论功能，并在页面设置中允许评论。
+:::
+
+## 相关页面
+
+- [评论](/config/comment) — 评论样式配置
+- [导航栏](/config/navbar) — 将留言板添加到导航菜单
+- [自定义页面](/pages/custom-page) — 自定义页面创建指南

docs/config/moments.md

@@ -0,0 +1,82 @@
+# 瞬间
+
+瞬间是 WarmIsland 主题支持的内容模块之一，用于发布简短的想法、动态和碎片化内容。类似于社交媒体的「朋友圈」或「微博」，适合记录日常灵感和即时想法。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `moments_page_title` | 文本 | `瞬间` | 页面标题 |
+| `moments_style` | 下拉 | `timeline` | 展示样式：`timeline` / `cards` / `masonry` |
+| `moments_loading_mode` | 下拉 | `infinite_scroll` | 加载方式：`infinite_scroll` / `pagination` |
+| `moments_page_size` | 数字 | `10` | 每页显示数量 |
+
+## 前置依赖
+
+::: danger
+瞬间功能依赖 Halo 的 **PluginMoments** 插件。如果未安装此插件，瞬间页面将无法正常工作。
+
+安装方式：Halo 后台 → **插件** → **安装** → 搜索「Moments」→ 安装并启用。
+:::
+
+## 详细说明
+
+### 页面标题（moments_page_title）
+
+瞬间页面的标题，显示在页面顶部。可以根据个人偏好自定义：
+
+```yaml
+moments_page_title: "瞬间"       # 默认
+moments_page_title: "动态"       # 替代方案
+moments_page_title: "Moments"    # 英文站点
+```
+
+### 展示样式（moments_style）
+
+| 值 | 说明 |
+| --- | --- |
+| `timeline` | 时间线样式，按时间顺序垂直排列，左侧有时间轴连线（默认） |
+| `cards` | 卡片样式，以网格卡片形式展示，每条瞬间独立成卡 |
+| `masonry` | 瀑布流样式，类似 Pinterest 的错落排列，适合图片较多的瞬间 |
+
+::: tip
+如果你的瞬间以文字为主，推荐 `timeline` 样式，时间感更强；如果图片较多，推荐 `masonry` 样式，能更好地展示图片内容。
+:::
+
+### 加载方式（moments_loading_mode）
+
+| 值 | 说明 |
+| --- | --- |
+| `infinite_scroll` | 无限滚动，滚动到底部自动加载更多（默认） |
+| `pagination` | 传统分页，页面底部显示分页导航 |
+
+### 每页显示数量（moments_page_size）
+
+每次加载/每页显示的瞬间数量。默认为 10 条。
+
+- 设为较小值（5–8）可加快首屏加载速度
+- 设为较大值（15–20）可减少翻页/加载次数
+
+```yaml
+moments_page_size: 10  # 默认
+```
+
+## 内置功能
+
+### 图片网格
+
+瞬间中包含的多张图片会以网格形式排列展示，自动计算列数和尺寸，确保图片不变形。
+
+### 点赞与评论
+
+每条瞬间支持点赞和评论功能，由 Halo 核心和 PluginMoments 插件提供。
+
+### 图片灯箱
+
+瞬间中的图片支持点击放大查看，基于 LightGallery 实现，与文章详情页的灯箱体验一致。
+
+## 相关页面
+
+- [图库](/config/photos) — 图库页面配置
+- [评论](/config/comment) — 评论样式配置
+- [瞬间页面](/pages/moments) — 瞬间模板与结构说明

docs/config/navbar.md

@@ -0,0 +1,78 @@
+# 导航栏
+
+导航栏是站点全局可见的核心组件，承载着页面导航、搜索入口和主题切换等功能。WarmIsland 提供了三种导航栏样式和灵活的功能开关。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `navbar_style` | 下拉 | `glass` | 导航栏样式：`glass` / `minimal` / `float` |
+| `navbar_show_search` | 开关 | `true` | 显示搜索按钮 |
+| `navbar_show_theme_switch` | 开关 | `true` | 显示主题切换按钮 |
+
+## 详细说明
+
+### 导航栏样式（navbar_style）
+
+| 值 | 说明 |
+| --- | --- |
+| `glass` | 毛玻璃效果，背景模糊半透明，与页面内容产生层次感（默认） |
+| `minimal` | 极简风格，纯色背景，线条简洁，适合内容导向型站点 |
+| `float` | 浮动样式，导航栏悬浮于内容之上，带有圆角和阴影 |
+
+::: tip
+`glass` 样式在滚动时会产生毛玻璃模糊效果，视觉效果最佳但需要浏览器支持 `backdrop-filter`。在不支持的浏览器中会自动降级为半透明背景。
+:::
+
+### 显示搜索按钮（navbar_show_search）
+
+开启后，导航栏右侧会显示搜索按钮。点击按钮或按 `Ctrl + K`（macOS 为 `⌘ + K`）快捷键即可打开搜索面板。
+
+::: danger
+搜索功能依赖 Halo 的 **PluginSearchWidget** 插件。如果未安装此插件，搜索按钮将无法正常工作。请确保已在 Halo 后台安装并启用该插件。
+
+安装方式：Halo 后台 → **插件** → **安装** → 搜索「Search Widget」→ 安装并启用。
+:::
+
+### 显示主题切换按钮（navbar_show_theme_switch）
+
+开启后，导航栏右侧会显示主题切换按钮，访客可以在浅色/深色模式之间切换。按钮的标签文案可在 [基础设置](/config/basic) 中的 `label_theme_switch` 配置项自定义。
+
+## 菜单配置
+
+导航栏的菜单项通过 Halo 后台管理，而非主题设置面板。配置步骤如下：
+
+1. 登录 Halo 后台管理控制台
+2. 进入 **菜单** → 创建或编辑菜单组
+3. 添加菜单项，支持以下类型：
+   - **页面** — 链接到已创建的页面
+   - **分类** — 链接到文章分类
+   - **自定义链接** — 任意 URL
+4. 确保菜单组被设置为主菜单（主题会自动读取主菜单渲染导航栏）
+
+::: tip
+建议菜单项数量控制在 5–7 个以内，过多会导致移动端体验下降。移动端会自动切换为汉堡菜单（☰），点击后展开侧滑菜单面板。
+:::
+
+## 快捷键
+
+| 快捷键 | 功能 |
+| --- | --- |
+| `Ctrl + K` / `⌘ + K` | 打开搜索面板 |
+| `Esc` | 关闭搜索面板 |
+
+## 移动端适配
+
+在移动端（屏幕宽度 ≤ 768px），导航栏会自动进行以下调整：
+
+- 菜单项折叠为汉堡菜单（☰）
+- 点击汉堡图标展开侧滑菜单面板
+- 搜索和主题切换按钮移入侧滑菜单
+- 导航栏高度适当缩减以节省屏幕空间
+
+## 相关页面
+
+- [基础设置](/config/basic) — 站点名称、Logo、标签文案配置
+- [样式设置](/config/style) — 配色方案与动画效果配置
+- [Hero 首屏](/config/hero) — 首屏区域配置
+- [快速开始](/guide/getting-started) — 导航菜单配置步骤

docs/config/photos.md

@@ -0,0 +1,101 @@
+# 图库
+
+图库是 WarmIsland 主题支持的照片展示模块，提供多种布局样式和分组功能，适合摄影师、设计师或任何需要展示图片集合的用户。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `photos_page_title` | 文本 | `图库` | 页面标题 |
+| `photos_style` | 下拉 | `masonry` | 展示样式：`masonry` / `grid` / `carousel` |
+| `photos_columns` | 数字 | `3` | 列数 |
+| `photos_show_ungrouped` | 开关 | `false` | 显示未分组图片 |
+| `photos_show_group_title` | 开关 | `true` | 显示分组标题 |
+
+## 前置依赖
+
+::: danger
+图库功能依赖 Halo 的 **PluginPhotos** 插件。如果未安装此插件，图库页面将无法正常工作。
+
+安装方式：Halo 后台 → **插件** → **安装** → 搜索「Photos」→ 安装并启用。
+:::
+
+## 详细说明
+
+### 页面标题（photos_page_title）
+
+图库页面的标题，显示在页面顶部。
+
+```yaml
+photos_page_title: "图库"       # 默认
+photos_page_title: "相册"       # 替代方案
+photos_page_title: "Gallery"    # 英文站点
+```
+
+### 展示样式（photos_style）
+
+| 值 | 说明 |
+| --- | --- |
+| `masonry` | 瀑布流样式，图片按原始比例错落排列，充分利用空间（默认） |
+| `grid` | 网格样式，图片统一裁剪为正方形或固定比例，整齐划一 |
+| `carousel` | 轮播样式，图片以轮播方式逐张展示，适合精选照片 |
+
+::: tip
+`masonry` 样式适合图片尺寸差异较大的场景（如混合横竖版照片）；`grid` 样式适合图片尺寸统一的场景（如统一裁剪的摄影作品）；`carousel` 样式适合精选少量优质照片展示。
+:::
+
+### 列数（photos_columns）
+
+控制网格和瀑布流布局中的图片列数。默认为 3 列。
+
+- 桌面端按设定列数显示
+- 平板端自动缩减列数
+- 移动端固定为 1–2 列
+
+```yaml
+photos_columns: 3  # 默认，3 列
+photos_columns: 4  # 更紧凑的布局
+photos_columns: 2  # 更宽松的布局
+```
+
+::: tip
+列数选择建议：2 列适合大图展示，3 列是通用平衡选择，4 列及以上适合缩略图式浏览。
+:::
+
+### 显示未分组图片（photos_show_ungrouped）
+
+开启后，「全部」视图中会显示未分配到任何分组的图片。未分组图片区域的标题为「全部」。
+
+关闭时，未分组的图片仅在「全部」视图中以合并方式展示，不单独标注分组。
+
+### 显示分组标题（photos_show_group_title）
+
+控制「全部」视图中是否显示各分组的标题。
+
+- **开启**（默认）— 每个分组的图片前会显示分组名称作为分隔标题
+- **关闭** — 所有图片合并展示，不显示分组标题
+
+::: tip
+如果分组较多且每个分组图片较少，建议关闭分组标题以获得更流畅的浏览体验。如果分组清晰且每个分组图片较多，建议开启以帮助访客快速定位。
+:::
+
+## 内置功能
+
+### 分组导航
+
+图库页面顶部显示分组导航标签，访客可以按分组筛选查看图片。点击「全部」查看所有图片，点击具体分组名称只查看该分组的图片。
+
+### 图片灯箱
+
+所有图片支持点击放大查看，基于 LightGallery 实现：
+
+- 点击图片弹出灯箱查看大图
+- 支持左右切换浏览同组图片
+- 支持缩放、全屏等操作
+- 按 `Esc` 或点击背景关闭灯箱
+
+## 相关页面
+
+- [瞬间](/config/moments) — 瞬间页面配置
+- [样式设置](/config/style) — 圆角与容器宽度配置
+- [图库页面](/pages/photos) — 图库模板与结构说明

docs/config/style.md

@@ -0,0 +1,147 @@
+# 样式设置
+
+样式设置控制 WarmIsland 主题的全局视觉表现，包括配色方案、强调色、圆角风格、容器宽度、动画效果以及自定义 CSS。通过这些配置，你可以快速打造出独一无二的站点外观。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `color_scheme` | 单选 | `system` | 配色方案：`system` / `light` / `dark` |
+| `accent_color` | 颜色 | `#d4764e` | 全局强调色 |
+| `border_radius` | 下拉 | `medium` | 圆角风格：`small` / `medium` / `large` |
+| `layout_container_width` | 下拉 | `medium` | 容器宽度：`narrow` / `medium` / `wide` |
+| `layout_sidebar` | 开关 | `false` | 启用侧边栏（开发中） |
+| `animation_enabled` | 开关 | `true` | 全局动画总开关 |
+| `animation_breath` | 开关 | `true` | 呼吸动画效果 |
+| `animation_scroll_reveal` | 开关 | `true` | 滚动渐入动画 |
+| `animation_cursor_glow` | 开关 | `false` | 光感跟随效果 |
+| `custom_css` | 代码 | — | 自定义 CSS 代码 |
+
+## 详细说明
+
+### 配色方案（color_scheme）
+
+控制站点的明暗模式，提供三种选择：
+
+| 值 | 说明 |
+| --- | --- |
+| `system` | 跟随系统偏好，自动适配用户操作系统的深色/浅色模式设置 |
+| `light` | 始终使用浅色模式 |
+| `dark` | 始终使用深色模式 |
+
+::: tip
+选择 `system` 时，主题会监听操作系统的 `prefers-color-scheme` 媒体查询，实时响应用户的系统设置变化。访问者也可以通过导航栏的主题切换按钮手动覆盖当前模式。
+:::
+
+### 强调色（accent_color）
+
+强调色是 WarmIsland 主题的灵魂，它会影响全站以下元素的颜色：
+
+- 链接悬停色
+- 按钮背景色
+- 标签高亮色
+- 进度条颜色
+- 选中状态颜色
+- Hero 区域渐变色的组成部分
+
+默认值 `#d4764e` 是暖屿标志性的暖橘色，与主题的温暖气质相呼应。
+
+::: tip
+选择强调色时，建议同时考虑浅色和深色模式下的可读性。可以在 [CSS 变量](/customize/css-variables) 页面查看所有受影响的变量，进行更精细的调整。
+:::
+
+```yaml
+# 常见强调色参考
+accent_color: "#d4764e"  # 暖橘（默认）
+accent_color: "#6366f1"  # 靛蓝
+accent_color: "#10b981"  # 翠绿
+accent_color: "#f43f5e"  # 玫红
+accent_color: "#8b5cf6"  # 紫罗兰
+```
+
+### 圆角风格（border_radius）
+
+控制全站组件的圆角大小，影响卡片、按钮、输入框等元素：
+
+| 值 | 说明 | 适用场景 |
+| --- | --- | --- |
+| `small` | 小圆角，偏硬朗风格 | 技术博客、极简风格 |
+| `medium` | 中等圆角，平衡美观与严谨 | 通用场景（默认） |
+| `large` | 大圆角，柔和亲切 | 生活博客、个人日记 |
+
+### 容器宽度（layout_container_width）
+
+控制页面主内容区域的最大宽度：
+
+| 值 | 说明 |
+| --- | --- |
+| `narrow` | 窄容器，适合以文字阅读为主的站点 |
+| `medium` | 中等宽度，兼顾阅读体验与信息密度（默认） |
+| `wide` | 宽容器，适合图片较多的站点或需要更大展示空间的场景 |
+
+### 侧边栏（layout_sidebar）
+
+::: danger
+侧边栏功能目前仍在开发中，此选项暂不可用。开启后不会产生实际效果，请关注后续版本更新。
+:::
+
+### 动画效果
+
+WarmIsland 提供了丰富的动画效果，所有动画都可以独立开关：
+
+#### 全局动画总开关（animation_enabled）
+
+关闭后，以下所有动画效果将一并禁用。适合追求极致性能或偏好静态页面的用户。
+
+#### 呼吸动画（animation_breath）
+
+启用后，Hero 区域的背景光球会产生缓慢的呼吸脉动效果，营造温暖柔和的氛围感。光球的大小和透明度会周期性变化。
+
+#### 滚动渐入（animation_scroll_reveal）
+
+启用后，页面元素在滚动进入视口时会以淡入+上移的方式渐次出现，增强浏览的节奏感。
+
+::: tip
+滚动渐入动画基于 Intersection Observer API 实现，对性能影响极小。如果页面内容较多，建议保持开启以提升浏览体验。
+:::
+
+#### 光感跟随（animation_cursor_glow）
+
+启用后，鼠标移动时会在光标附近产生柔和的光晕跟随效果，为页面增添灵动感。
+
+::: warning
+光感跟随效果在移动端不会生效（因为移动端没有鼠标光标）。在低端设备上可能会影响渲染性能，如遇卡顿建议关闭。
+:::
+
+### 自定义 CSS（custom_css）
+
+在此处编写自定义 CSS 代码，会注入到全站所有页面的 `<style>` 标签中。可以用来覆盖主题默认样式或添加全新样式。
+
+```css
+/* 示例：修改正文字体 */
+body {
+  font-family: "LXGW WenKai", sans-serif;
+}
+
+/* 示例：自定义卡片悬停效果 */
+.post-card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.1);
+}
+
+/* 示例：隐藏特定元素 */
+.hero-scroll-indicator {
+  display: none;
+}
+```
+
+::: tip
+如需更系统地自定义样式，推荐使用 [CSS 变量](/customize/css-variables) 方式，只需修改变量值即可影响全站，无需逐个覆盖选择器。详见 [自定义 CSS](/customize/custom-css) 页面。
+:::
+
+## 相关页面
+
+- [CSS 变量](/customize/css-variables) — 全部可用的 CSS 变量列表
+- [自定义 CSS](/customize/custom-css) — 深入了解自定义样式的方法
+- [基础设置](/config/basic) — 站点名称、Logo 等基础信息配置
+- [导航栏](/config/navbar) — 导航栏样式与功能配置