Narrate · 叙
在喧嚣里，留一处文字自留地。
简约、优雅、阅读优先的 Halo 2 博客主题。以编辑杂志的版式组织内容：大字号首屏、编号荐读、克制的朱红点缀与充足留白，让文章本身成为页面的主角。主题移植自 Typecho 主题 Narrate · 叙，保留原有视觉语言，并针对 Halo 的模板、设置与插件体系重新实现。
- 点击加入：QQ交流群
- Halo 版本：
>= 2.27.0 - 主题版本：
1.0.0 - 演示站点：https://www.puresky.top/
- 开源仓库：https://github.com/imorisun/halo-theme-narrate
- 问题反馈：https://github.com/imorisun/halo-theme-narrate/issues
- 许可证：GPL-3.0
适用场景
- 个人博客、独立写作站点，尤其是长文、随笔、读书笔记与生活记录
- 希望以杂志式排版呈现内容的站点：精选、荐读、分类导览和编号列表
- 需要深色模式、移动端阅读体验与克制动效的站点
- 已使用「瞬间」「链接管理」「朋友圈」等 Halo 插件，希望前台页面风格统一的站点
核心特性
编辑杂志风的首页
- 首屏主张：大字号主张句 + 自动轮播的旋转词；眉题、背景大字、站点英文标语与页脚标语均可在主题设置中修改
- 此刻状态栏：实时时钟、按访客本地时间切换的分时段问候，以及按发布时间排序的最新文章入口
- 精选与荐读：首页首篇自动成为主视觉，后续文章以编号列表呈现「编辑荐读」（最多 4 篇）
- 分类导览：按后台勾选的分类逐块展示，每个分类列出最新 4 篇文章；未选择分类时整块隐藏
- 瞬间横滑：安装「瞬间」插件后，首页以横向轨道展示最新瞬间，末端提供「查看全部瞬间」入口
- 首字水印：首页使用可配置的背景大字，文章页与独立页面以标题首字作为背景装饰，强化版面节奏
文章与阅读
- 阅读进度条、预计阅读时长与访问量
- 根据正文
h2/h3自动生成文章目录，无标题时自动收窄正文版心 - 代码高亮使用主题内置的 highlight.js 与本地样式，不依赖 CDN
- 正文图片懒加载、自动包裹
figure，点击可打开灯箱并支持左右切换 - 分类、标签、版权说明、上一篇 / 下一篇与 Halo 评论组件
- 深色模式下同步 Halo 插件组件的配色方案
页面与侧栏
| 页面 | 说明 |
|---|---|
| 首页 | 首屏、此刻状态栏、精选、编辑荐读、瞬间、分类导览与分页 |
| 文章 | 目录、代码高亮、图片灯箱、版权、上下篇、评论 |
| 独立页面 | 标准页面版式；slug 为 guestbook 时自动切换为留言板眉题与文案 |
| 关于（自定义模板） | 站点图标头像、站点统计、站点信息与正文，创建页面时选择「关于」模板 |
| 归档 | 按年 / 月分组，附带全年与每月文章数量统计 |
| 分类 / 标签 | 总览页与对应归档页；归档页带侧栏 |
| 作者 | 作者文章归档，带同一套侧栏 |
| 友情链接 | 需「链接管理」插件；支持分组筛选、友链卡片与申请表单（算术验证码） |
| 朋友圈 | 需「朋友圈」插件；聚合友站最新文章并分页 |
| 瞬间列表 / 详情 | 需「瞬间」插件；列表支持标签筛选、点赞、评论弹层与分页，详情页含点赞与评论 |
| 错误页 | 404 与通用错误兜底 |
分类、标签与作者归档页的侧栏包含最新文章、标签云、随机友链（需「链接管理」插件）与站点统计。
全局体验
- 搜索：安装「搜索组件」插件后，导航栏显示搜索按钮，支持
Ctrl / ⌘ + K快捷键 - 深色模式：跟随系统偏好，也可手动切换；选择保存在浏览器本地，首次渲染前完成初始化以避免闪烁
- 响应式：桌面多栏布局，移动端提供抽屉导航
- 可访问性：尊重
prefers-reduced-motion，主要操作可用键盘完成 - 页脚：品牌区、导航、全部分类、随机友链、版权信息、驱动信息与备案链接
安装
- 在 GitHub Releases 下载最新 ZIP，或在 Halo 应用市场搜索「Narrate」安装。
- 进入 Halo 后台 → 外观 → 主题 → 安装主题，上传 ZIP。
- 启用「Narrate · 叙」，按需在 主题设置 中调整文案与开关后保存。
- 建议在 外观 → 菜单 创建主菜单（首页 / 归档 / 分类 / 标签 / 关于），未配置时主题会显示默认导航。
主题目录名必须为
halo-theme-narrate，与theme.yaml的metadata.name保持一致。
插件搭配（可选）
以下插件均为可选；未安装时对应入口与区块会自动隐藏或使用空状态，不影响主题基础功能。
| 插件 | 作用 | 涉及的页面 / 区块 |
|---|---|---|
| 瞬间（PluginMoments） | 短内容发布 | 首页瞬间横滑、/moments 列表与详情、点赞与评论 |
| 链接管理（PluginLinks） | 友情链接数据 | /links 友链页、页脚随机友链、侧栏友链、关于页朋友统计 |
| 朋友圈（PluginFriends） | 聚合友站 RSS | /friends 朋友圈页 |
| 搜索组件（PluginSearchWidget） | 站内搜索 | 导航栏搜索按钮与搜索弹窗 |
| 评论组件（PluginCommentWidget） | 评论能力 | 文章、独立页面与瞬间列表 / 详情 |
主题设置
设置分为 4 组，修改后点击保存；若未立即生效，可在主题列表中执行「重载主题配置」。
品牌与首屏
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 站点标语 | 首页首屏、关于页与友链页的简介；留空时使用 Halo 站点副标题 | 空 |
| 站点英文标语 | 页头与页脚站点名称下方的英文后缀；留空时使用 SERENE | SERENE |
| 首屏背景大字 | 首屏背景的巨幅描边字符，页脚品牌区沿用同一字符 | 叙 |
| 首屏眉题 | 首屏主张句上方的短标签 | 叙 · 个人博客 |
| 页脚站点标语 | 页脚站点名称下方的一行文字 | Narrate · 以文为名 |
| 启用在线中文字体 | 从第三方服务加载 LXGW 975 圆体；关闭后使用系统字体 | 开启 |
| 首屏主张句 | 使用 {rot} 标记旋转词位置 |
在喧嚣里，留一处{rot}。 |
| 首屏旋转词 | 每行一条，依次轮播 | 笔墨栖居地 / 思想避风港 / 文字小天地 / 心灵自留地 |
首页模块
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 启用瞬间 | 需安装「瞬间」插件 | 开启 |
| 瞬间展示数量 | 首页横滑展示的瞬间条数，范围 1–20 | 6 |
| 分类导览展示的分类 | 多选；留空时隐藏分类导览 | 空 |
| 问候语 | 每行一条，依次对应 05:00–11:00、11:00–13:00、13:00–18:00、18:00–23:00、23:00–次日 05:00 | 内置 5 条 |
问候语不足 5 条时以最后一条补齐；首屏旋转词同样按回车分隔，并兼容逗号、顿号分隔的旧配置。
文章与阅读
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 显示文章目录 | 正文包含 h2 / h3 时显示 |
开启 |
| 启用代码高亮 | 使用主题内置 highlight.js | 开启 |
| 显示阅读量 | 读取 Halo 访问统计 | 开启 |
| 版权协议名称 | 文章底部版权说明 | CC BY-NC-SA 4.0 |
| 版权协议链接 | 版权协议跳转地址 | Creative Commons 官方页面 |
底部
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 页脚友链展示数量 | 需「链接管理」插件，随机展示指定数量 | 8 |
| 备案信息链接 | 每项包含显示文本与跳转链接，最多 5 条 | 空 |
使用说明与注意事项
- 在线字体：主题默认从第三方字体服务
fontsapi.zeoseven.com加载 LXGW 975 圆体。若站点访问该服务较慢，可在「品牌与首屏」中关闭，正文会自动回退到苹方、HarmonyOS Sans、微软雅黑或系统字体。 - 文章目录：仅在正文包含
h2/h3时生成；纯图片或短文章会自动使用无目录的窄版心。 - 瞬间页面：
/moments与/moments/{name}由「瞬间」插件提供路由，主题覆盖其前台模板；未安装插件时这些地址不可用，属于预期行为。 - 友链与朋友圈：
/links、/friends分别依赖「链接管理」「朋友圈」插件。 - 评论区：由 Halo 评论组件渲染；未安装评论插件或文章关闭评论时，会显示「评论已关闭」。
- 深色模式：访客的手动选择保存在浏览器
localStorage的narrate-theme键中；清除浏览器数据后会重新跟随系统偏好。 - 关于页头像：优先使用站点图标，未设置时回退到主题内置头像。
- 系统能力：站点 Logo、favicon、SEO、统计代码等由 Halo 系统设置或插件负责，主题不重复提供，避免冲突。
- 界面语言：主题文案为简体中文，暂未提供多语言资源。
- 演示数据：主题不包含演示文章、分类或图片；安装后展示站点自身内容。
- 升级与卸载：主题设置保存在 Halo ConfigMap 中，升级不会丢失；卸载主题不会删除文章、页面、分类、标签等站点内容。
常见问题
| 问题 | 处理方式 |
|---|---|
| 修改设置后页面没有变化 | 在主题列表点击「重载主题配置」，或确认已保存设置 |
| 首页没有瞬间区块 | 安装并启用「瞬间」插件，确认主题设置已开启，且插件中已有内容 |
| 搜索按钮不显示 | 安装并启用「搜索组件」插件 |
| 文章页没有目录 | 确认文章正文使用了 h2 / h3，且「显示文章目录」已开启 |
| 字体加载慢或显示异常 | 关闭「启用在线中文字体」，使用系统字体 |
| 友链页或朋友圈页 404 | 安装并启用对应插件 |
| 评论区不显示 | 安装并启用评论组件，并确认文章/页面已开启评论 |
| 关于页样式不对 | 编辑页面，在页面设置中选择「关于」自定义模板 |
兼容性
- 要求 Halo >= 2.27.0（见
theme.yaml的spec.requires）。底部「备案信息链接」使用了 Halo 2.22 引入的array设置组件。 - 主题仅影响前台展示，不修改 Halo 核心文件，不依赖数据库结构变更。
- 可选插件未安装、已停用或版本不满足时，相关区块会隐藏或回退到空状态。
开发与构建
pnpm install
pnpm dev # 监听 src/ 并持续构建 templates/
pnpm build # 类型检查 + 构建 templates/ + 打包 dist/halo-theme-narrate-1.0.0.zip
pnpm build-only # 仅类型检查与构建，不打包 ZIP
pnpm check # 格式化、Lint 与类型检查
src/：页面模板、partials/片段、CSS 与 TypeScript 源码。public/：原样复制到templates/的静态资源，如内置头像与 highlight.js。templates/：构建产物，Halo 只读取主题根目录下的templates/，请勿手工修改。scripts/package.mjs：打包时临时移走pnpm-lock.yaml，避免锁文件被theme-package误打进主题包。theme.yaml：主题元数据；settings.yaml：主题设置表单。- 发布 GitHub Release 时，CD 工作流会自动构建 ZIP、上传至 Release 并同步到 Halo 应用市场。
许可与致谢
- 主题代码以 GPL-3.0 发布。
- 视觉与内容结构移植自 Typecho 主题 Narrate · 叙（作者：Jane，https://github.com/JaneLens）。
- 代码高亮：highlight.js（BSD-3-Clause）；等宽字体：JetBrains Mono（OFL-1.1）。
- 在线中文字体：LXGW 975 圆体（OFL-1.1），由第三方字体服务
fontsapi.zeoseven.com提供。 - 主题图标中的「叙」字使用 Noto Serif SC（OFL-1.1）轮廓绘制。