Joe Next

基于 Joe3 重构的 Halo 2 博客主题。保留 Joe 的样子和功能，前端用 Astro + TypeScript 重写：不再依赖 jQuery，页面之间无刷新切换，深浅色、手机端和无障碍都重新做过一遍。

本主题由 Joe3 衍生，已获得原作者授权。Joe3 的前身为 qinhua 的 halo-theme-joe2.0。

演示与交流

• 演示站：xhhao.com（Handsome）
• 文档：docs.lik.cc
• QQ 交流群：

功能

页面与浏览

• 无刷新切换页面（swup），支持浏览器原生的过渡动画；导航、音乐播放器在切页时不中断
• 浮岛式导航：阅读文章时显示当前章节与阅读进度，点开就是迷你目录
• 导航子菜单使用独立的明暗配色，支持鼠标悬停、箭头按钮与键盘展开，未配置图标的菜单仅显示文字
• 控制中心：一键切换深浅色、侧栏、动画和正文字号，另有站点动态时间线与「我的足迹」（读过的文章、自己的评论，只保存在访客浏览器里）
• 深色模式可以由访客自己切换（默认跟随系统），也可以按时段自动切换，或固定为浅色 / 深色
• 音乐播放器：歌单可以自己上传，也可以通过 Meting 接口使用网易云、QQ 音乐、酷狗、酷我；可配置平台、资源类型、资源 ID 与额外查询参数，支持歌词、播放顺序和锁屏控制
• 随便看看、键盘快捷键（j / k 切换上一篇下一篇，? 查看全部）、自定义右键菜单

首页

• 全屏大图与一言、轮播、精选推荐、瞬间叠放卡片
• 文章列表：左图右文的列表或双列卡片，按分类标签页切换，加载更多（可滚动到底自动加载）或分页
• 继续阅读（回到上次读到的位置）、新文章与更新标记、卡片上的评论者头像
• 那年今日：往年今天写过的文章

文章

• 沉浸式头图、文章目录、字数与阅读时长、过期提醒
• 文章系列：选几个标签当系列，文章顶部显示「第 n / 共 N 篇」和整个系列的目录
• 代码块：语言标签、复制、行号、长代码折叠（语法高亮由 shiki 插件负责）
• 选中文字后可以复制、引用到评论或分享；点赞、打赏、分享海报
• 上一篇 / 下一篇卡片、相关文章、版权信息

其他页面

• 归档：时间轴与发文热力图，支持按年、按月查看
• 分类、标签：卡片或标签样式
• 瞬间、图库、友情链接（带访客申请）、朋友圈（订阅友链的 RSS）、装备、留言板

站点

• 页脚：运行天数、建站纪念进度、站点数据、导航分组、备案号
• SEO / GEO：canonical、Open Graph / Twitter 分享卡片、JSON-LD 结构化数据、RSS 订阅发现，每项都能单独关闭，方便和 SEO 插件共存
• 性能：首屏只加载必需的样式和脚本，特效、轮播、灯箱等按需下载；图片使用 Halo 生成的缩略图

安装

需要 Halo 2.27.0 或更高版本。

1. 在 Releases 下载最新的 theme-joe-next-<版本>.zip
2. 在 Halo 控制台的「主题」页面点右上角「主题管理」，再点「安装主题」上传 zip 文件，安装后启用
3. 主题详情页里「详情」后面的标签页就是主题设置，分为外观、导航、动效与特效、首页、博主卡片、侧边栏、文章、分享与打赏、代码块、页面、SEO、页脚与高级 12 个分组

升级：在主题详情页右上角的 ··· 里选「升级」，上传新版本的 zip，已保存的设置不会丢。新版本增加了设置项时，再选一次「重载主题配置」。

从 Joe3 迁移：设置项已经重新整理，与 Joe3 不兼容，启用后需要重新设置一遍。Joe 编辑器插入的正文短代码（标签页、提示框、卡片等）不再支持，旧文章里的这些内容会按普通文字显示。

推荐插件

主题不依赖任何插件也能运行；装上对应插件后，相应的功能和页面才会出现。

页面模板：在「页面」里新建页面，模板选择「留言板」「友链」或「朋友圈」，例如把别名设为 friends 就能通过 /friends 访问朋友圈。

上线前：确认 Halo 的外部访问地址（启动参数 halo.external-url，见 Halo 文档的配置参考）是正式域名。规范链接、分享卡片和结构化数据里的地址都按它生成。

开发

开发环境：Node.js 22.23.4（见 .nvmrc）、pnpm 10。

nvm use
pnpm install
pnpm dev        # 监听 src/ 变化并重新构建到 templates/

将主题目录放到 Halo 工作目录的 themes/theme-joe-next/，在控制台安装并启用。开发时建议关闭模板缓存：SPRING_THYMELEAF_CACHE=false。

qa:shots、qa:snapshot、qa:a11y 需要一个启用了本主题的 Halo（默认 http://127.0.0.1:8091，用 HALO_URL 修改）和本机 Chrome；ROUTES、WIDTHS 环境变量可限定页面与宽度。重构样式时先对修改前后各拍一次快照再对比，可发现肉眼难以察觉的样式变化。

发布：在 GitHub 创建 Release 后，CD 工作流会自动构建并把主题包上传到 Release 附件。

目录结构

src/
├── pages/              页面模板，每个文件对应一个 Halo 模板（index、post、archives…）
├── layouts/            BaseLayout：head、导航、页脚、悬浮按钮、全局脚本
├── components/
│   ├── head/           配置注入、动态样式、SEO
│   ├── navbar/         顶部导航、移动端抽屉、控制中心、音乐播放器
│   ├── aside/          侧栏及各侧栏组件
│   ├── blogger/        博主卡片、社交账号
│   ├── home/           首页轮播、大图、精选推荐
│   ├── list/           文章列表项、分页、分类/标签网格、归档
│   ├── post/           文章正文、分享、版权、评论、系列、那年今日
│   ├── moment/         瞬间
│   └── links/          友链、申请友链
├── scripts/
│   ├── app.ts          全站脚本入口
│   ├── pages/          页面专属脚本入口
│   ├── features/       独立功能模块（明暗模式、导航、点赞、轮播、音乐…）
│   ├── content/        正文处理（目录、灯箱、分享）
│   ├── core/           基础工具（DOM、配置、存储、提示）
│   └── effects/        鼠标/背景特效（按需加载）
├── styles/             原生 CSS（嵌套语法），按 base / components / layout / content / pages 拆分，目录即级联层
├── config/             前后端共享的配置契约与 SpEL 表达式
└── data/               社交图标、内联 SVG 等静态数据
public/assets/          运行时按路径引用的资源（Logo、头像框、鼠标皮肤、字体、默认图片）
integrations/           Astro 构建后处理（Thymeleaf 标签还原、CSS 级联层、模块预加载）
docs/screenshots/       README 截图（不进主题包）

Halo配套小程序

TinyTale微信小程序：
TinyTale 是一款基于 Halo 博客系统的微信小程序，可以展示博客文章、图库、瞬间等内容。简洁、美观、易用，是你的博客的最佳搭档。
不仅仅是展示，你还可以在小程序快速发布瞬间和图库，记录生活非常方便舒服。
详细地址：https://www.jiewen.run/archives/TinyTale-formal-edition

相对 Joe3 的变化

• 技术栈： jQuery、Isotope、fancybox、Draggabilly、WOW.js、NProgress、Qmsg、ClipboardJS、lazysizes、Vue 2 均由原生 API 或 npm 包替代，第三方库通过 pnpm 管理并锁定版本。
• 图标： iconfont 图标字体与 Font Awesome 改为 Iconify 图标（lucide、Remix Icon、Simple Icons），构建时内联为 SVG（src/config/icons.ts），不加载图标字体也不请求 CDN；菜单项图标、自定义社交图标均使用 Halo 的 Iconify 图标选择器，保存图标名称并由前台组件按需加载，兼容已保存的 SVG；自定义社交图标保留所选颜色。
• 卡片背景： 博主卡片、手机抽屉与目录面板使用原图，保留 GIF 动画。
• 页面标题： 首页读取 Halo 系统设置中的站点主副标题，在主题设置「SEO → 标题分隔符」选择「主标题 - 副标题」或「主标题｜副标题」；副标题留空时只显示主标题。内容页沿用所选分隔符连接页面标题与站点主标题。
• 代码块： 语法高亮、行号、复制、折叠及外观全部由代码高亮插件控制；主题不再提供代码块设置或包装脚本。
• 评论： 只使用 Halo 评论扩展点（评论组件插件），不再内置 Waline。
• 友链排序： 分组与组内链接默认完整跟随后台排列。原先已保存创建时间排序的站点，可在「页面 → 友情链接」将两项排序切换为「友链插件中的顺序」。
• 已移除： 天气组件、百度收录检测、内置 Prism 代码高亮（改由 shiki 插件负责）、APlayer 侧栏歌单（改为导航栏的音乐播放器）、Joe 编辑器的正文短代码（<joe-tabs>、<joe-alert>、卡片、折叠、时间线、音视频、B 站视频等，旧文章里的这些标签按普通文字显示），以及 Joe3 中未被引用的库和模板（halo-comment、KaTeX、jquery-ui 等）。
• 设置项： 重新整理为 12 个分组，统一键名与说明文字，与 Joe3 及 Joe Next 0.1 之前的配置不兼容，升级后需要在后台重新设置。已删除不再生效的设置（预载图、外部资源地址、旧版自定义 CSS/JS、Waline 等）。
• 修复： 分类/标签/作者页分页地址、年度时间轴重复、作者页标题、page_links 在未安装链接插件时报错等 Joe3 遗留问题。

许可证

CC BY-NC-SA 4.0，与 Joe3 保持一致：可以自由使用和修改，但不能用于商业用途，修改后的版本需要以相同许可证发布并注明出处。