Halo Theme GitHub

一款仿 GitHub 个人主页风格的 Halo 2 主题，由 Monster 基于官方 theme-vite-starter 开发。

主题将博客内容组织成类似 GitHub Profile 的界面，支持响应式布局、动态贡献图、站点动态、文章搜索，以及友链、瞬间、图库、留言板等 Halo 内容页面。

演示站点：点击跳转

点击加入GitHub主题交流群

功能说明

• GitHub 风格的顶部栏、个人资料区、菜单标签和内容卡片。
• 首页展示最新文章、年度贡献图和站点动态。
• 贡献图汇总文章、瞬间、标签、分类和图库的发布或创建记录，支持切换年份、按日期筛选动态。
• 支持文章列表、文章详情、独立页面、分类、标签和分页。
• 内置站内搜索，可搜索已发布的文章和独立页面；支持点击搜索框或按 / 唤起，按 Esc 关闭。
• 搜索快捷键会自动识别文章和瞬间评论编辑器等输入区域，不会干扰输入网址或包含 / 的评论内容。
• 自动读取 Halo 的主菜单，支持为不同菜单路径配置 Iconify 图标，并自动高亮当前菜单。
• 支持显示文章数、评论数和访问量。
• 适配 Halo 友链、瞬间和图库页面。
• 提供带随机循环评论弹幕效果的留言板自定义模板，避免同时出现大量重复评论。
• 友链页面支持展示本站友链资料和自助申请表单；申请会提交为留言板评论，供站长人工审核。
• 适配 Personal Assets 插件的个人资产页面。
• 支持菜单栏下方全宽公告横幅和全站哀悼灰阶模式。
• 支持自定义页面背景色、强调色、友链默认头像、实时天气和站点页脚。
• 支持网易云歌单及自定义 API 数据源的播放器，可显示在左下角或搜索框后的右上角。
• 支持在侧边栏展示公众号二维码、动态站点标签云和站点分类标签。
• 支持桌面端和移动端响应式布局。

环境要求

• Halo：>= 2.0.0
• 推荐使用最新稳定版 Halo 2
• 从源码构建时需要 Node.js 20+、Corepack 和 pnpm 10

基础设置

个人资料头像和顶部 Logo 使用 Halo 的站点 Logo；顶部站点标题、页面标题和页脚站点名称使用 Halo 后台的站点标题。请在 Console 的「设置」->「基本设置」中配置。

公告

在「公告」中可以开启全宽公告横幅并填写公告内容。公告显示在前端菜单栏下方，支持多行纯文本。

开启「哀悼模式」后，主题会为全站应用灰阶效果，适合发布哀悼性质的公告。关闭开关即可恢复原有配色。

侧边栏

在「侧边栏」中可按需开启以下内容，未开启或没有配置内容时不会占用前端空间：

标签和分类数据通过 Halo 公共接口异步加载；接口不可用时仅隐藏对应区块，不会影响页面主体渲染。

菜单与图标

主题读取 Halo 的主菜单。请先进入「外观」->「菜单」，创建或编辑主菜单并添加需要展示的菜单项。

主题预置了以下路径的图标配置：

在「图标配置」中可以修改这些默认值。其他菜单可通过「其他菜单栏自定义图标」添加路径与 Iconify 图标名称，例如：

图标名称可在 Iconify 查询。路径没有匹配规则时，主题使用「未匹配菜单默认图标」。

样式设置

天气城市、纬度和经度用于访客定位不可用时的备用天气位置，默认城市为深圳。顶部天气组件和右上角播放器会使用与其他顶部按钮一致的主题色系。

开启天气后，主题默认请求浏览器定位权限并显示访问者所在地的实时天气。访客拒绝定位、定位超时、浏览器不支持或页面未使用 HTTPS 时，主题会自动使用后台填写的备用城市及坐标。天气数据使用无需 API Key 的 Open-Meteo，不会保存访客位置。

悬浮播放器

在「样式」设置中开启「悬浮播放器」并填写歌单 ID 后，可通过「播放器显示位置」选择左下角或右上角。右上角播放器显示在顶部搜索框之后，采用紧凑的 macOS 音乐播放器样式，只显示动态歌词、上一首、播放或暂停、下一首和循环模式；窄屏设备会自动显示为左下角悬浮播放器。默认接口使用网易云音乐的 Meting 歌单格式，可在后台选择顺序或随机作为默认播放模式，并会尝试自动播放；若浏览器拦截自动播放，会在用户首次点击页面后继续播放。

「音乐 API 地址」中的 {id} 会自动替换为歌单 ID。自定义接口可接入其他音乐平台，需允许浏览器跨域访问，并返回歌曲数组或 data 包装的歌曲数组；每首歌曲需包含可播放地址，字段支持 title / name、artist / author、url，封面可使用 cover / pic。

关于设置

/about 页面会自动使用主题的关于页布局。在「关于设置」中可配置：

• 右侧 README 内容中的个人标签；左侧头像、名称和描述复用「基础设置」中的资料。
• 关于本站、建站历程和各模块显示开关。
• 技能与认证的名称、Iconify 图标和进度。
• 约定标题、描述、起止日期，页面会自动计算进度。
• 联系方式的名称、链接和 Iconify 图标。

关于本站留空时，主题会优先显示 Halo 关于页的正文内容。

底部设置

未填写的备案、站点运行时间或服务商内容不会显示。Halo 后台设置的页脚内容也会通过主题的 <halo:footer /> 一并显示。

内容页面配置

文章、分类和标签

主题原生支持 Halo 的文章、独立页面、分类和标签，无需额外插件。常用菜单路径如下：

• 文章归档：/archives
• 分类列表：/categories
• 标签列表：/tags
• 独立页面：使用页面发布后生成的固定链接

首页贡献图通过 Halo API 读取公开内容。如果某类内容不存在或对应扩展未安装，会跳过该类数据，不影响文章内容展示。

留言板

1. 在 Halo Console 进入「内容」->「页面」，新建一个页面。
2. 开启该页面的评论功能。
3. 在页面的「模板」中选择「留言板」。
4. 发布页面，并将它的固定链接加入主菜单。

留言板会读取该页面已审核且未隐藏的评论，以飘屏方式展示，并每 30 秒检查一次新留言。评论区是否可用取决于 Halo 的评论系统和该页面的评论设置。

友链

安装并启用 Halo 官方「链接管理」插件，添加链接分组和链接后访问 /links。主题会按分组展示友链，并使用「友链设置」中的友链默认头像处理缺失或加载失败的 Logo。

在「友链设置」中可自定义本站友链名称、地址、头像、描述、友链页面和 RSS 订阅地址。开启「启用友链申请」后，友链页会展示可复制的本站友链资料及申请表单；访客提交成功后会看到“申请已提交到留言板，等待站长审核。”提示，申请内容会作为留言板评论提交，管理员审核后可手动添加正式友链。

瞬间

安装并启用 Halo 官方「瞬间」插件后，可使用：

• 瞬间列表：/moments
• 瞬间详情：由插件自动生成

主题支持瞬间标签筛选、图片/视频/音频等媒体内容、点赞与评论统计以及详情评论区。

图库

安装并启用 Halo 官方「图库管理」插件后访问 /photos。主题支持图库分组筛选、响应式图片网格和分页。

个人资产

安装并启用 Personal Assets 插件后访问 /personalassets。主题内置了与 GitHub 风格一致的资产页面模板，资产数据和页面标题等设置由插件管理。

许可

本项目使用 GPL-3.0 License。

相关链接

• 作者网站：https://ffbf.top
• 源码仓库：https://github.com/dengchuanfu/halo-theme-github
• 问题反馈：https://github.com/dengchuanfu/halo-theme-github/issues