# 快速开始

WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主题。暖如灯火，静如留白——它以柔和的色调和舒缓的节奏回归内容本身，为记录与阅读留出一方安静从容的角落。

## 主题特色

- 🎨 **暖色调设计** — 呼吸光球、毛玻璃导航栏、滚动渐入动画
- 🌙 **深色模式** — 跟随系统/浅色/深色三种方案，平滑切换
- 📱 **响应式布局** — 桌面到手机完美适配
- 📝 **沉浸阅读** — 侧边目录、进度条、代码高亮、图片灯箱
- 🔌 **插件生态** — 瞬间、图库、友链、订阅动态、豆瓣、装备、Steam
- 🔒 **默认零第三方请求** — 静态资源全部自托管，可选 API 默认留空
- ⚙️ **灵活配置** — 17 个分组 / 126 个配置项，无需改代码

## 前置要求

- **Halo >= 2.27.0**（主题 `theme.yaml` 声明 `requires: ">=2.27.0"`；页面布局契约与微信读书页面依赖 2.27 的能力）
- 已安装并运行 Halo 实例
- 如需插件页面（瞬间、图库、友链、订阅等），另需安装对应插件

## 安装方式

### 方式一：应用市场安装（推荐）

1. 登录 Halo 后台管理控制台
2. 进入 **主题** → **安装**
3. 搜索「WarmIsland 暖屿」或从应用市场安装
4. 点击 **启用** 激活主题

### 方式二：本地上传安装

1. 从 [源码仓库](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland) 的 Releases / 发行版页面下载最新版本的 `.zip` 安装包
2. 登录 Halo 后台管理控制台
3. 进入 **主题** → **安装** → 选择 **本地上传**
4. 上传下载的 `.zip` 文件
5. 点击 **启用** 激活主题

::: warning
从源码自行打包时，必须先执行 `pnpm release`（build → snapshot → package）。
只上传源码或漏跑构建的 ZIP 会因缺少 `templates/` 导致首页 404，详见 [FAQ](/faq)。
:::

## 初始配置

安装并启用主题后，建议按以下顺序进行初始配置：

### 第一步：基础信息

进入 **主题** → **设置** → **基础设置**：

- 填写 **站点名称**（显示在导航栏和页脚）
- 填写 **站点描述**（用于 SEO）
- 上传 **自定义 Logo** 和 **Favicon**

### 第二步：外观样式

进入 **样式设置**：

- 选择 **配色方案**（跟随系统/浅色/深色）与 **主题配色**（11 套预设）
- 设置 **强调色**（留空则跟随所选配色，暖屿·赤陶为 `#d4764e`）
- 选择 **圆角风格** 和 **容器宽度**

### 第三步：导航菜单

1. 进入 Halo 后台 → **菜单** → 创建新菜单
2. 添加菜单项（首页、归档、瞬间等）
3. 主题自动读取主菜单渲染导航栏

### 第四步：Hero 首屏

进入 **Hero 首屏** 设置：

- 设置主标题和副标题
- 选择描述文案来源（默认「无」/ 一言 / 自定义）；默认不显示描述、不发起请求；「自定义一言 API」字段在来源非「无」时显示并默认预填 `https://v1.hitokoto.cn/`（仅「一言」模式生效），清空该字段则使用内置本地句子库（零外部请求）
- 可选上传背景图片

### 第五步：页脚信息

进入 **页脚** 设置：

- 填写版权信息
- 添加社交链接（GitHub、微博等）
- 可选添加自定义 HTML（统计代码等）

### 可选：订阅动态页面

如需展示博友文章动态，安装官方「链接管理」（PluginLinks）插件并维护 RSS 订阅源，
再新建一个页面选择「订阅」自定义模板即可。原先的「朋友圈」插件已不再提供，
详见[订阅页面](/pages/subscriptions)。

## 下一步

- [基础设置](/config/basic) — 完整的主题配置说明
- [样式设置](/config/style) — 调整配色、圆角、动画
- [订阅配置](/config/subscriptions) — feed 聚合动态设置