主题开发在线文档：https://site.ikunwl.com/data/docs/#ch3
1 主题目录结构
主题放在 templates/{主题名}/ 目录下，以下是以/mytheme/主题名为主演示。
判定一个目录是否为可用主题：目录存在且包含 index.php（Theme::exists()），theme.json 提供展示信息。
templates/mytheme/
theme.json 主题信息（名称/标题/版本/作者/简介/预览图）
index.php 首页模板（必需，判定主题存在与否的依据）
category.php 分类页模板（可选，缺失时回退 default 主题）
site.php 站点详情页模板
search.php 搜索页模板
submit.php 提交站点页模板
article_list.php 文章列表页模板（article 插件启用后生效）
article_detail.php 文章详情页模板
error.php 错误页模板（收到 $code / $message）
header.php 公共头部片段（可选；Theme::partial('header') 加载）
footer.php 公共底部片段（可选；含 before_footer / after_footer 钩子）
404.php 404 兼容页（可选，参考模板）
css/ 样式文件（Theme::asset('css/xxx.css') 引用）
js/ 脚本文件（Theme::asset('js/xxx.js') 引用）
screenshot.png 主题截图（可选，后台主题管理展示）
admin.php 主题自带后台设置页（可选；存在时主题管理当前主题卡片出现「设置」，见开发文档 3.8）
缺失的模板文件会自动回退到 templates/default/ 对应文件（Theme::render() / Theme::partial() 均支持回退），因此可以只覆盖想自定义的页面。直接复制 templates/default/ 目录作为新主题起点是最快的做法。
2 theme.json 配置
每个主题可包含 theme.json，由 Theme::getInfo() 读取并合并到默认值（名称/标题/版本/作者/简介），供后台主题管理展示；缺失时使用目录名等默认值。
{
"name": "default",
"title": "我的主题",
"version": "1.0",
"author": "你的名字",
"description": "主题简介",
"preview": ""
}
| 字段 | 必填 | 说明 |
|---|---|---|
name |
否 | 主题标识（默认取目录名，后台展示用） |
title |
否 | 显示名称（默认取目录名） |
version |
否 | 版本号（默认 1.0） |
author |
否 | 作者 |
description |
否 | 简介 |
preview |
否 | 预览图 URL 或留空（screenshot.png 会被自动识别为截图） |
除 theme.json 外，系统还会自动检测 index.php / category.php / site.php / search.php / submit.php 是否存在并记录到 files 字段，供后台展示文件齐全度。
其他详见主题开发文档~偷偷说一句，可以把文档丢给 AI，就可以写主题了哦，文档很完善了，期待你的主题，做好主题可以在：> 茶馆 < 分享主题，也可以在：> 反馈 < 反馈你所遇到的问题。