主题

Utterlog 支持系统自带主题和用户自定义主题。两者隔离存储，升级时系统主题会跟着镜像更新，你自己上传的主题不受影响。

系统自带主题

当前发行版附带：

Azure — 默认主题，简洁蓝色调
Flux — 动效优先，适合图文并茂的博客
Utterlog 2026 — 极简直角设计系统

在后台「主题」页一键切换。系统主题代码位于 API 镜像内的 /app/public/themes/，每次升级自动更新到最新版本。

用户自定义主题

上传自己的主题：后台「主题」→「上传主题」，选 .zip 包。存储位置是 uploads/themes/<slug>/（宿主机 bind-mount），升级镜像不会覆盖。

主题结构

my-theme/
├── theme.json            # 元数据
├── screenshot.png        # 后台预览图 (800x600 推荐)
├── README.md             # 说明（可选）
└── templates/
    ├── home.html         # 首页
    ├── post.html         # 文章详情
    ├── archive.html      # 归档
    ├── category.html     # 分类页
    ├── tag.html          # 标签页
    └── partials/
        ├── header.html
        ├── footer.html
        └── comment.html

`theme.json` 字段

{
  "name": "我的主题",
  "slug": "my-theme",
  "version": "1.0.0",
  "author": "作者名",
  "description": "主题一句话介绍",
  "preview": "screenshot.png",
  "compatibility": ">=1.0.0"
}

模板引擎

Utterlog 用 Go 的 html/template。模板里能用这些上下文变量：

{{ .Site }} — 站点标题、URL、描述、logo 等
{{ .Posts }} — 文章列表（列表页）
{{ .Post }} — 当前文章（详情页）
{{ .User }} — 当前登录用户（未登录则 nil）
{{ partial "header" . }} — 引入 templates/partials/header.html

完整上下文结构见源码 api/internal/theme/context.go（注释里列了所有字段）。

主题开发工作流

在本地开发：git clone 一个起始主题（推荐 fork Azure）
运行 docker compose up -d 让 api 起来
把你的主题目录 bind-mount 进 api 容器：-v ./my-theme:/app/public/themes/my-theme
后台切换到该主题，浏览器改模板立刻刷新可见
稳定后打包成 .zip 分享给其他用户

分享主题

我们准备在 utterlog.com 联盟中心站做一个主题市场（等一批好主题出现后启用）。暂时可以：

在 GitHub 上新建 utterlog-theme-<name> 仓库
README 里贴上截图和 utterlog.com/install-theme?url=... 链接
开 issue 到 utterlog/utterlog 请求添加到官方目录

下一步

插件（类似机制，可扩展 API 和后台）
升级（了解升级时主题如何处理）

主题