Halo 主题开发

要解决什么问题

Halo 用 Spring Boot + WebFlux + Thymeleaf 渲染前台页面；主题本质是模板目录 + theme.yaml（及可选的 settings.yaml）。版本迭代里 API、VO 字段名、模板变量 会变，单靠训练数据写 Finder 调用或读变量，很容易对不上当前版本。

技能如何组织内容

• 开发流程：在 Halo 工作目录 themes/ 下建与 metadata.name 同名的主题包 → 写配置 → 在 templates/ 写模板 → 控制台安装激活；开发期可关 Thymeleaf 缓存（如 SPRING_THYMELEAF_CACHE=false）。
• 起步模板：assets/theme-minimal/（无构建链、8 个模板文件）适合快速原型；assets/theme-vite/ 集成 vite-plugin-halo-theme，适合新主题（布局片段、CSS 工具链）。
• Thymeleaf 速查：技能内附核心语法要点，并指向官方教程全文链接。
• References 索引：按场景拆文档——结构与配置、Vite 插件、模板路由与变量、全局变量（site / theme / theme.config）、各类 Finder API、静态资源引用、自定义标签、i18n、官方插件、注解字段、打包 CLI、Halo 侧 Thymeleaf 实践等；写模板或查数据前先对表读对应 reference。

边界与注意点

Important（技能原文强调）：访问模板变量或调用 Finder 前，务必先查 References 中的在线文档，不要凭记忆猜字段名或方法签名。纯 HTML 主题与 Vite 主题在资源引用、include/slot 语法上路径不同，选 starter 后应跟对应 reference（如 vite-plugin.md vs static-resources.md）。