halo-theme-dev

Halo 主题开发

基于目标主题开展工作，仅在任务需要 Halo 特定约定时获取最新的 Halo 文档。不要依赖训练数据中记忆的 Finder 签名、模板变量或配置字段。

确定目标

• 编辑前检查 theme.yaml、settings.yaml、软件包清单、构建配置，以及有代表性的模板。
• 确定 theme.yaml 中的 spec.requires 和实际 Halo 版本。不要擅自提高版本要求或替换主题的构建系统。
• 确认运行时模板是直接在 templates/ 中编写，还是从 src/ 等源目录生成。

按需获取文档

1. 当任务涉及 Halo 主题配置、模板、Finder API、全局变量、资源、注解、i18n、打包或插件集成时，从主题文档索引开始。
2. 仅当文档路径不明确或任务涉及多个文档部分时，才使用完整的 Halo 文档索引。
3. 只获取与当前任务相关的 Markdown 页面。默认不要加载 llms-full.txt。
4. 对于与版本相关的工作，还应阅读主题 API 更新日志，然后根据目标版本或现有模板核实具体字段和签名。目标版本优先于当前网站上的文档。

如果无法访问在线文档，请尽可能基于目标代码检出版本和已安装的依赖继续工作，并说明哪些内容无法核实，而不要猜测。

Halo 特定边界

• 主题目录名称应与 theme.yaml 中的 metadata.name 保持一致。
• 对于使用构建工具的主题，应编辑源模板和资源，然后运行现有构建；不要手动编辑生成的 templates/ 输出或带哈希的资源。
• 编写表达式前，请阅读当前的 Thymeleaf 指南。Halo 2.26 使用 Thymeleaf 3.1，其中 #request、#response、#session 和 #servletContext 不可用。不要猜测表达式方法，也不要从请求对象推导页面 URL；请使用文档中说明的模板变量和永久链接。
• 默认将站点标识和全局注入视为由 Halo 管理。使用 site.logo、系统 SEO 设置、Halo 的 head 处理以及 <halo:footer />；只有在主题特定覆盖且有系统回退值时，才添加主题设置。向 settings.yaml 添加字段前，请查阅当前的设置指南。
• 不要重复添加 Halo 注入的描述或关键词。Canonical、Open Graph、Twitter Card 和结构化数据是可选的主题／插件功能，必须遵循当前的 SEO 指南，并使用避免冲突的开关。
• 保留项目既有的 Thymeleaf 布局和资源约定。使用 Finder 方法、模板变量、Halo 工具、自定义标签或页面布局约定前，请查阅相关文档。集成官方前端小组件时，请遵循当前插件集成指南中的共享配色方案约定。
• 仅在创建新主题时使用下方的入门资源。切勿用入门模板替换现有主题。

入门模板

assets/ 目录提供两个开箱即用的主题模板：

• assets/theme-minimal/ — 无需构建工具的极简主题，包含标准路由模板；适合快速原型开发或简单主题
• assets/theme-vite/ — 使用 vite-plugin-halo-theme 的 Vite 项目模板（新主题推荐使用）；支持复用局部布局，并包含 CSS 工具链

使用方法：将目录复制到 Halo 工作目录中的 themes/，确保文件夹名称与 theme.yaml 中的 metadata.name 一致，然后在 Console 中安装并启用。

验证

在适用时，运行主题现有的构建和打包检查。在兼容的 Halo 实例上测试每种已更改的模板类型或集成路径；至少覆盖受影响的路由以及一个使用共享布局的页面。检查渲染后的 HTML、资源加载情况、分页或空状态（如相关），以及浏览器控制台错误。