> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 主题开发

## 准备工作

### [准备工作](/developer-guide/theme/prepare.md)

- [搭建开发环境](/developer-guide/theme/prepare.md#搭建开发环境)
- [新建一个主题](/developer-guide/theme/prepare.md#新建一个主题)
- [通过模板创建](/developer-guide/theme/prepare.md#通过模板创建)
- [创建第一个页面模板](/developer-guide/theme/prepare.md#创建第一个页面模板)
- [安装主题](/developer-guide/theme/prepare.md#安装主题)
## AI 辅助

### [AI 辅助](/developer-guide/theme/ai.md)

- [提供文档上下文](/developer-guide/theme/ai.md#提供文档上下文)
- [核对版本与源码](/developer-guide/theme/ai.md#核对版本与源码)
- [生成前检查清单](/developer-guide/theme/ai.md#生成前检查清单)
- [Agent Skill](/developer-guide/theme/ai.md#agent-skill)
## 目录结构

### [目录结构](/developer-guide/theme/structure.md)
## 配置文件

### [配置文件](/developer-guide/theme/config.md)

- [格式示例](/developer-guide/theme/config.md#格式示例)
- [字段详解](/developer-guide/theme/config.md#字段详解)
- [更新配置](/developer-guide/theme/config.md#更新配置)
- [从 1.x 迁移](/developer-guide/theme/config.md#从-1x-迁移)
## Thymeleaf 模板语法

### [Thymeleaf 模板语法](/developer-guide/theme/thymeleaf.md)

- [确认运行环境](/developer-guide/theme/thymeleaf.md#确认运行环境)
- [认识常用表达式](/developer-guide/theme/thymeleaf.md#认识常用表达式)
- [输出文本和 HTML](/developer-guide/theme/thymeleaf.md#输出文本和-html)
- [组合文本和处理空值](/developer-guide/theme/thymeleaf.md#组合文本和处理空值)
- [遍历和条件渲染](/developer-guide/theme/thymeleaf.md#遍历和条件渲染)
- [定义局部变量](/developer-guide/theme/thymeleaf.md#定义局部变量)
- [复用模板片段](/developer-guide/theme/thymeleaf.md#复用模板片段)
- [使用表达式工具](/developer-guide/theme/thymeleaf.md#使用表达式工具)
- [向 JavaScript 输出数据](/developer-guide/theme/thymeleaf.md#向-javascript-输出数据)
- [常见错误](/developer-guide/theme/thymeleaf.md#常见错误)
- [排查模板错误](/developer-guide/theme/thymeleaf.md#排查模板错误)
## 静态资源

### [静态资源](/developer-guide/theme/static-resources.md)

- [模板标签引用](/developer-guide/theme/static-resources.md#模板标签引用)
- [API 引用](/developer-guide/theme/static-resources.md#api-引用)
- [#theme.route(path)](/developer-guide/theme/static-resources.md#themeroutepath)
## 设置选项

### [设置选项](/developer-guide/theme/settings.md)

- [区分系统设置与主题设置](/developer-guide/theme/settings.md#区分系统设置与主题设置)
- [定义表单](/developer-guide/theme/settings.md#定义表单)
- [更新配置](/developer-guide/theme/settings.md#更新配置)
- [从 1.x 迁移](/developer-guide/theme/settings.md#从-1x-迁移)
## 主题附带资源

### [主题附带资源](/developer-guide/theme/extension-resources.md)

- [提供资源](/developer-guide/theme/extension-resources.md#提供资源)
- [允许的资源](/developer-guide/theme/extension-resources.md#允许的资源)
- [加载和更新](/developer-guide/theme/extension-resources.md#加载和更新)
- [卸载边界](/developer-guide/theme/extension-resources.md#卸载边界)
- [源码参考](/developer-guide/theme/extension-resources.md#源码参考)
## 国际化

### [国际化](/developer-guide/theme/i18n.md)

- [定义消息](/developer-guide/theme/i18n.md#定义消息)
- [在模板中使用](/developer-guide/theme/i18n.md#在模板中使用)
- [页面级消息](/developer-guide/theme/i18n.md#页面级消息)
- [在 JavaScript 中使用](/developer-guide/theme/i18n.md#在-javascript-中使用)
- [切换和测试语言](/developer-guide/theme/i18n.md#切换和测试语言)
## 模板路由

### [模板路由](/developer-guide/theme/template-route-mapping.md)

- [主要模板](/developer-guide/theme/template-route-mapping.md#主要模板)
- [自定义模板](/developer-guide/theme/template-route-mapping.md#custom-templates)
## 全局变量

### [全局变量](/developer-guide/theme/global-variables.md)

- [site](/developer-guide/theme/global-variables.md#site)
- [#halo.matchVersion(constraint)](/developer-guide/theme/global-variables.md#halomatchversionconstraint)
- [theme](/developer-guide/theme/global-variables.md#theme)
- [按登录状态条件渲染](/developer-guide/theme/global-variables.md#按登录状态条件渲染)
- [访问量统计脚本](/developer-guide/theme/global-variables.md#访问量统计脚本)
## 页面模板与变量

### [首页](/developer-guide/theme/template-variables/home.md)

- [路由信息](/developer-guide/theme/template-variables/home.md#路由信息)
- [变量](/developer-guide/theme/template-variables/home.md#变量)
- [类型定义](/developer-guide/theme/template-variables/home.md#类型定义)

### [文章](/developer-guide/theme/template-variables/post.md)

- [路由信息](/developer-guide/theme/template-variables/post.md#路由信息)
- [变量](/developer-guide/theme/template-variables/post.md#变量)
- [类型定义](/developer-guide/theme/template-variables/post.md#类型定义)

### [单页面](/developer-guide/theme/template-variables/page.md)

- [路由信息](/developer-guide/theme/template-variables/page.md#路由信息)
- [变量](/developer-guide/theme/template-variables/page.md#变量)
- [类型定义](/developer-guide/theme/template-variables/page.md#类型定义)

### [文章归档](/developer-guide/theme/template-variables/archives.md)

- [路由信息](/developer-guide/theme/template-variables/archives.md#路由信息)
- [变量](/developer-guide/theme/template-variables/archives.md#变量)
- [类型定义](/developer-guide/theme/template-variables/archives.md#类型定义)

### [文章标签集合](/developer-guide/theme/template-variables/tags.md)

- [路由信息](/developer-guide/theme/template-variables/tags.md#路由信息)
- [变量](/developer-guide/theme/template-variables/tags.md#变量)
- [类型定义](/developer-guide/theme/template-variables/tags.md#类型定义)

### [标签归档](/developer-guide/theme/template-variables/tag.md)

- [路由信息](/developer-guide/theme/template-variables/tag.md#路由信息)
- [变量](/developer-guide/theme/template-variables/tag.md#变量)
- [类型定义](/developer-guide/theme/template-variables/tag.md#类型定义)

### [文章分类集合](/developer-guide/theme/template-variables/categories.md)

- [路由信息](/developer-guide/theme/template-variables/categories.md#路由信息)
- [变量](/developer-guide/theme/template-variables/categories.md#变量)
- [类型定义](/developer-guide/theme/template-variables/categories.md#类型定义)

### [分类归档](/developer-guide/theme/template-variables/category.md)

- [路由信息](/developer-guide/theme/template-variables/category.md#路由信息)
- [变量](/developer-guide/theme/template-variables/category.md#变量)
- [类型定义](/developer-guide/theme/template-variables/category.md#类型定义)

### [作者归档](/developer-guide/theme/template-variables/author.md)

- [路由信息](/developer-guide/theme/template-variables/author.md#路由信息)
- [变量](/developer-guide/theme/template-variables/author.md#变量)
- [类型定义](/developer-guide/theme/template-variables/author.md#类型定义)

### [认证页面](/developer-guide/theme/template-variables/auth.md)

- [原理讲解](/developer-guide/theme/template-variables/auth.md#原理讲解)
- [自定义场景](/developer-guide/theme/template-variables/auth.md#自定义场景)

### [错误页面](/developer-guide/theme/template-variables/error.md)

- [路由信息](/developer-guide/theme/template-variables/error.md#路由信息)
- [变量](/developer-guide/theme/template-variables/error.md#变量)
## Finder API

### [文章分类](/developer-guide/theme/finder-apis/category.md)

- [getByName(name)](/developer-guide/theme/finder-apis/category.md#getbynamename)
- [getByNames(names)](/developer-guide/theme/finder-apis/category.md#getbynamesnames)
- [list(page,size)](/developer-guide/theme/finder-apis/category.md#listpagesize)
- [listAll()](/developer-guide/theme/finder-apis/category.md#listall)
- [listAsTree()](/developer-guide/theme/finder-apis/category.md#listastree)
- [listAsTree(name)](/developer-guide/theme/finder-apis/category.md#listastreename)
- [getParentByName(name)](/developer-guide/theme/finder-apis/category.md#getparentbynamename)
- [getBreadcrumbs(name)](/developer-guide/theme/finder-apis/category.md#getbreadcrumbsname)
- [类型定义](/developer-guide/theme/finder-apis/category.md#类型定义)

### [文章标签](/developer-guide/theme/finder-apis/tag.md)

- [getByName(name)](/developer-guide/theme/finder-apis/tag.md#getbynamename)
- [getByNames(names)](/developer-guide/theme/finder-apis/tag.md#getbynamesnames)
- [list(page,size)](/developer-guide/theme/finder-apis/tag.md#listpagesize)
- [listAll()](/developer-guide/theme/finder-apis/tag.md#listall)
- [类型定义](/developer-guide/theme/finder-apis/tag.md#类型定义)

### [文章](/developer-guide/theme/finder-apis/post.md)

- [getByName(postName)](/developer-guide/theme/finder-apis/post.md#getbynamepostname)
- [content(postName)](/developer-guide/theme/finder-apis/post.md#contentpostname)
- [cursor(postName)](/developer-guide/theme/finder-apis/post.md#cursorpostname)
- [cursorByCategory(postName)](/developer-guide/theme/finder-apis/post.md#cursorbycategorypostname)
- [listAll()](/developer-guide/theme/finder-apis/post.md#listall)
- [random(maxSize)](/developer-guide/theme/finder-apis/post.md#randommaxsize)
- [`list({...})`](/developer-guide/theme/finder-apis/post.md#list)
- [list(page,size)](/developer-guide/theme/finder-apis/post.md#listpagesize)
- [listByCategory(page,size,categoryName)](/developer-guide/theme/finder-apis/post.md#listbycategorypagesizecategoryname)
- [listByTag(page,size,tag)](/developer-guide/theme/finder-apis/post.md#listbytagpagesizetag)
- [listByOwner(page,size,owner)](/developer-guide/theme/finder-apis/post.md#listbyownerpagesizeowner)
- [archives(page,size)](/developer-guide/theme/finder-apis/post.md#archivespagesize)
- [archives(page,size,year)](/developer-guide/theme/finder-apis/post.md#archivespagesizeyear)
- [archives(page,size,year,month)](/developer-guide/theme/finder-apis/post.md#archivespagesizeyearmonth)
- [类型定义](/developer-guide/theme/finder-apis/post.md#类型定义)

### [独立页面](/developer-guide/theme/finder-apis/single-page.md)

- [getByName(pageName)](/developer-guide/theme/finder-apis/single-page.md#getbynamepagename)
- [content(pageName)](/developer-guide/theme/finder-apis/single-page.md#contentpagename)
- [list(page,size)](/developer-guide/theme/finder-apis/single-page.md#listpagesize)
- [类型定义](/developer-guide/theme/finder-apis/single-page.md#类型定义)

### [评论](/developer-guide/theme/finder-apis/comment.md)

- [getByName(name)](/developer-guide/theme/finder-apis/comment.md#getbynamename)
- [list(ref,page,size)](/developer-guide/theme/finder-apis/comment.md#listrefpagesize)
- [listReply(commentName,page,size)](/developer-guide/theme/finder-apis/comment.md#listreplycommentnamepagesize)
- [类型定义](/developer-guide/theme/finder-apis/comment.md#类型定义)

### [作者](/developer-guide/theme/finder-apis/contributor.md)

- [getContributor(name)](/developer-guide/theme/finder-apis/contributor.md#getcontributorname)
- [getContributors(names)](/developer-guide/theme/finder-apis/contributor.md#getcontributorsnames)
- [类型定义](/developer-guide/theme/finder-apis/contributor.md#类型定义)

### [导航菜单](/developer-guide/theme/finder-apis/menu.md)

- [getByName(name)](/developer-guide/theme/finder-apis/menu.md#getbynamename)
- [getPrimary()](/developer-guide/theme/finder-apis/menu.md#getprimary)
- [类型定义](/developer-guide/theme/finder-apis/menu.md#类型定义)

### [站点统计](/developer-guide/theme/finder-apis/site-stats.md)

- [getStats()](/developer-guide/theme/finder-apis/site-stats.md#getstats)
- [类型定义](/developer-guide/theme/finder-apis/site-stats.md#类型定义)

### [主题](/developer-guide/theme/finder-apis/theme.md)

- [activation()](/developer-guide/theme/finder-apis/theme.md#activation)
- [getByName(themeName)](/developer-guide/theme/finder-apis/theme.md#getbynamethemename)
- [类型定义](/developer-guide/theme/finder-apis/theme.md#类型定义)

### [插件](/developer-guide/theme/finder-apis/plugin.md)

- [available(pluginName)](/developer-guide/theme/finder-apis/plugin.md#availablepluginname)
- [available(pluginName, requiresVersion)](/developer-guide/theme/finder-apis/plugin.md#availablepluginname-requiresversion)
## 自定义标签

### [自定义标签](/developer-guide/theme/template-tag.md)

- [halo:comment](/developer-guide/theme/template-tag.md#halocomment)
- [halo:footer](/developer-guide/theme/template-tag.md#halofooter)
## 模型元数据

### [模型元数据](/developer-guide/theme/annotations.md)

- [#annotations.get(extension,key)](/developer-guide/theme/annotations.md#annotationsgetextensionkey)
- [#annotations.getOrDefault(extension,key,defaultValue)](/developer-guide/theme/annotations.md#annotationsgetordefaultextensionkeydefaultvalue)
- [#annotations.contains(extension,key)](/developer-guide/theme/annotations.md#annotationscontainsextensionkey)
## 使用 Vite 开发主题

### [使用 Vite 开发主题](/developer-guide/theme/vite.md)

- [区分源码和构建产物](/developer-guide/theme/vite.md#区分源码和构建产物)
- [配置插件](/developer-guide/theme/vite.md#配置插件)
- [复用模板片段](/developer-guide/theme/vite.md#复用模板片段)
- [开发和构建](/developer-guide/theme/vite.md#开发和构建)
## 与插件集成

### [与插件集成](/developer-guide/theme/plugin-integration.md)

- [检查插件是否可用](/developer-guide/theme/plugin-integration.md#检查插件是否可用)
- [保留主题扩展点](/developer-guide/theme/plugin-integration.md#保留主题扩展点)
- [兼容插件前台页面](/developer-guide/theme/plugin-integration.md#兼容插件前台页面)
- [适配插件组件配色](/developer-guide/theme/plugin-integration.md#适配插件组件配色)
- [覆盖插件前台模板](/developer-guide/theme/plugin-integration.md#覆盖插件前台模板)
- [验证兼容性](/developer-guide/theme/plugin-integration.md#验证兼容性)
## 页面布局契约

### [页面布局契约](/developer-guide/theme/page-layout.md)

- [适配主题布局](/developer-guide/theme/page-layout.md#适配主题布局)
- [在主题页面中复用布局](/developer-guide/theme/page-layout.md#在主题页面中复用布局)
- [插件页面调用布局](/developer-guide/theme/page-layout.md#插件页面调用布局)
- [兼容状态](/developer-guide/theme/page-layout.md#兼容状态)
- [版本演进](/developer-guide/theme/page-layout.md#版本演进)
## UI 扩展

### [UI 扩展](/developer-guide/theme/ui-plugin.md)

- [目录结构](/developer-guide/theme/ui-plugin.md#目录结构)
- [入口文件](/developer-guide/theme/ui-plugin.md#入口文件)
- [使用 Vite 构建](/developer-guide/theme/ui-plugin.md#使用-vite-构建)
- [使用 Rsbuild 构建](/developer-guide/theme/ui-plugin.md#使用-rsbuild-构建)
- [输出格式和共享依赖](/developer-guide/theme/ui-plugin.md#输出格式和共享依赖)
## 主题调试与测试

### [主题调试与测试](/developer-guide/theme/testing.md)

- [建立开发反馈循环](/developer-guide/theme/testing.md#建立开发反馈循环)
- [定位常见问题](/developer-guide/theme/testing.md#定位常见问题)
- [覆盖页面和状态](/developer-guide/theme/testing.md#覆盖页面和状态)
- [记录可复核结果](/developer-guide/theme/testing.md#记录可复核结果)
## 图片优化

### [图片优化](/developer-guide/theme/image-optimization.md)

- [为什么使用响应式图片？](/developer-guide/theme/image-optimization.md#为什么使用响应式图片)
- [Finder API](/developer-guide/theme/image-optimization.md#finder-api)
- [HTTP API](/developer-guide/theme/image-optimization.md#http-api)
## 性能最佳实践

### [性能最佳实践](/developer-guide/theme/performance.md)

- [静态资源加载](/developer-guide/theme/performance.md#静态资源加载)
- [控制 Finder 调用](/developer-guide/theme/performance.md#控制-finder-调用)
- [图片优化](/developer-guide/theme/performance.md#图片优化)
- [验证](/developer-guide/theme/performance.md#验证)
## 主题 SEO

### [主题 SEO](/developer-guide/theme/seo.md)

- [设置页面标题](/developer-guide/theme/seo.md#设置页面标题)
- [使用 Halo 注入的元数据](/developer-guide/theme/seo.md#使用-halo-注入的元数据)
- [通过主题设置控制扩展标签](/developer-guide/theme/seo.md#通过主题设置控制扩展标签)
- [可选的结构化数据](/developer-guide/theme/seo.md#可选的结构化数据)
- [验证最终结果](/developer-guide/theme/seo.md#验证最终结果)
## 构建与打包

### [构建与打包](/developer-guide/theme/packaging.md)

- [配置打包命令](/developer-guide/theme/packaging.md#配置打包命令)
- [默认打包内容](/developer-guide/theme/packaging.md#默认打包内容)
- [谨慎使用 --all](/developer-guide/theme/packaging.md#谨慎使用---all)
- [发布前检查](/developer-guide/theme/packaging.md#发布前检查)
## 主题发布验收清单

### [主题发布验收清单](/developer-guide/theme/release-checklist.md)

- [构建并确认制品](/developer-guide/theme/release-checklist.md#构建并确认制品)
- [验证安装和升级](/developer-guide/theme/release-checklist.md#验证安装和升级)
- [覆盖页面和内容状态](/developer-guide/theme/release-checklist.md#覆盖页面和内容状态)
- [验证集成和浏览器表现](/developer-guide/theme/release-checklist.md#验证集成和浏览器表现)
- [配置持续发布（可选）](/developer-guide/theme/release-checklist.md#配置持续发布可选)
- [记录发布证据](/developer-guide/theme/release-checklist.md#记录发布证据)
## API 变更日志

### [API 变更日志](/developer-guide/theme/api-changelog.md)

- [2.26.0](/developer-guide/theme/api-changelog.md#2260)
- [2.25.0](/developer-guide/theme/api-changelog.md#2250)
- [2.24.1](/developer-guide/theme/api-changelog.md#2241)
- [2.23.0](/developer-guide/theme/api-changelog.md#2230)
- [2.22.8](/developer-guide/theme/api-changelog.md#2228)
- [2.22.1](/developer-guide/theme/api-changelog.md#2221)
- [2.22.0](/developer-guide/theme/api-changelog.md#2220)