# Gitea Mail Template
---

[English](../README.md)

Gitea Mail Template 为自托管的 [Gitea](https://about.gitea.com) 提供多种可选、适合的邮件模板风格。

> 最新发布版：[v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)

仓库包含数种主题的 Gitea 邮件模板，适合大多数的部署场景与应用范围。安装前，请根据 Gitea 版本查阅[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)，选择对应的发行包。

## 风格画廊

这里展示邮件模板通过预览工具呈现的实际渲染风格和效果。

| 预览 | 主题 | 样式特点 |
|---|---|---|
| ![Aurora](images/aurora.png) | **Aurora** | 深紫色背景、青绿色强调色、柔和光晕 |
| ![Bloom](images/bloom.png) | **Bloom** | 浅蓝色渐变、圆角卡片与按钮 |
| ![Ember](images/ember.png) | **Ember** | 暖橙色调、衬线标题、圆角按钮 |
| ![Heritage](images/heritage.png) | **Heritage** | 藏蓝与金色、双线边框、衬线字体 |
| ![Horizon](images/horizon.png) | **Horizon** | 蓝色强调色、灰色文字、居中白色卡片 |
| ![Ink](images/ink.png) | **Ink** | 报刊式布局、侧栏、衬线字体与首字下沉 |
| ![Mono](images/mono.png) | **Mono** | 黑白配色、红色强调色、直角边框 |
| ![Neon](images/neon.png) | **Neon** | 深色背景、粉红与青色、发光效果 |
| ![Terminal](images/terminal.png) | **Terminal** | 深色背景、等宽字体、绿色强调色 |
| ![Terra](images/terra.png) | **Terra** | 大地色调、陶土色按钮、衬线字体 |

截图仅展示当前默认构建效果，其他邮件类型和语言可通过[本地预览](#预览)查看；更新截图请参阅[截图指南](images/README.md)。

## 安装

### 选择安装来源

运行 `gitea --version` 确认部署的 Gitea 实例版本，再按照[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)选择模板版本。

> [!WARNING]
> 我们不建议直接从源码仓库拉取并构建，因为这些版本还未经过完全测试达到发行可用的水平。如果存在未知的模板参数过时或遗漏可能导致 Gitea 实例启动异常。

> [!TIP]
> 如果仍然需要从源码构建邮件模板，下方同样给出的相应步骤方法。

| 来源 | 邮件模板目录 | 准备步骤 |
|---|---|---|
| 发行版 | `themes/<名称>/mail/` | 下载并解压推荐版本的发行包 |
| 源码 | `build/themes/<名称>/mail/` | 使用 Go 1.24 或更高版本构建 |

从源码构建时，请在仓库根目录执行：

```bash
cd tools
go run . build all
cd ..
```
构建可用模板时需要依赖于 Gitea 官方仓库的资源文件，以确保来源的一致性。因此该命令会自动下载由`gitea.lock.json` 文件锁定的官方文件，后续构建无需再次下载，使用缓存目录资源即可运行。文件缺失或缓存损坏的处理方式见[更新官方快照](CONTRIBUTING.zh-CN.md#更新官方快照)。

### 安装主题

将所选主题 `mail/` 目录中的内容复制到 `<GITEA_CUSTOM>/templates/mail/`，然后重启 Gitea 即可生效。复制前请确认实例实际使用的自定义目录。以下是常见部署路径示例：

| 部署方式 | 自定义目录示例 |
|---|---|
| Linux Binary | `/var/lib/gitea/custom` |
| Docker | `/data/gitea` |
| Windows | `C:\gitea\custom` |

例如，在使用 systemd 管理 Gitea 的 Linux 主机上，从已解压的发行包目录执行：

```bash
systemctl stop gitea
mkdir -p /var/lib/gitea/custom/templates/mail
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
systemctl restart gitea
```

> [!TIP]
> 使用源码构建产物时，将复制来源改为 `build/themes/horizon/mail/.`。Docker 和 Windows 部署请使> 用相应的容器或服务管理方式暂停和重启。

### 切换主题

先备份或移除上一主题安装的文件，选择新的邮件主题依照上述安装步骤重新操作即可。

### 确认生效

使用测试账户触发密码重置等邮件通知，检查邮件样式和链接。管理后台的测试邮件按钮不使用自定义邮件模板，因此无法确认邮件模板是否生效。

## 预览

通过仓库中提供的预览工具，可以在部署前预览邮件不同主题，不同模板类型和语言的渲染效果

### 静态预览

首先需要在源码仓库中生成预览数据：

```bash
cd tools
go run . preview all
cd ..
```

在浏览器中打开 [preview/index.html](../preview/index.html) 即可。无需启动服务器。

### 热重载开发

```bash
cd tools
go run . dev
## 在终端中输入 Ctrl + C 即可终止服务器运行
cd ..
```

打开 [http://127.0.0.1:3456](http://127.0.0.1:3456)。Go 服务器监听主题文件、共享框架、锁文件与缓存、预览测试数据的变化。一旦监听到文件更改，服务器会将邮件模板重新构建后通过发送事件（SSE）刷新页面，以实现实时热重载。

### 控制和快捷键

| 控件 | 选项或快捷键 |
|---|---|
| 主题、模板、语言和视图 | `←` / `→` 切换选择框，`↑` / `↓` 选择选项 |
| 视图 | **Modern** 显示渲染结果，**Source** 显示生成的 HTML 文本 |
| 视口 | **Desktop**（1386 × 780）、**Mobile**（390 × 780）；快捷键 `d` / `m` |
| 信息面板 | `p` 展开或收起面板 |

> [!WARNING]
> 预览使用示例数据渲染模板。浏览器与邮件客户端对 CSS 的支持不同，部署前还需在目标邮件客户端中检查效果。

## 兼容性

- **最新测试：** Gitea 28.0.0
- **最新发布版：** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
- **上游 Gitea 28.1.0：** [PENDING]

## 项目目录结构

项目按共享框架、主题样式和构建工具组织。源码与文档纳入版本控制，下载的官方文件和生成的模板、预览数据不纳入版本控制。

### 版本控制中

```text
.github/                  # 工作流及维护脚本
  release-notes/          # 各版本的发行说明
  scripts/                # 文档更新、打包和 Gitea 发布脚本
  workflows/              # 验证和发布
docs/                     # 中文文档、文档索引和画廊图片
framework/                # 共享邮件控件和布局预设
  layouts/                # 各类邮件共用的布局预设
  mail/base/              # 页头、操作按钮、备用链接、侧栏和页脚
preview/index.html        # 预览界面
themes/<THEME_NAME>/      # 主题源码
tools/                    # Go 命令行工具、构建工具和测试
  builder/                # 官方模板适配和主题生成
  cli/                    # 命令定义和参数处理
  config/                 # 预览配置读取和校验
  data/                   # 邮件类型说明和预览示例数据
  preview/                # 邮件渲染、语言适配和开发服务器
  upstream/               # 官方快照下载、校验和翻译键发现
gitea.lock.json           # 官方版本标签、提交和文件校验值
README.md
```

官方模板提供通知内容、条件、主题行和链接；共享框架负责邮件呈现，主题通过元数据和 CSS 选择布局、定义样式。主题目录中不保存官方邮件源码或翻译文件。

### 不在版本控制中

以下文件由构建和预览命令生成，或按锁文件下载，无需手动维护或提交：

```text
build/themes/<THEME_NAME>/      # 主题构建结果
  mail/                         # 可安装到 Gitea 的邮件模板
  build.json                    # 构建来源和生成文件的校验记录
build/upstream/                 # 锁文件指定的官方模板、语言、资源和许可证
dist/                           # 默认输出的发行压缩包
preview/rendered.js             # 预览清单
preview/rendered/<LOCALE>.js    # 各语言的预览数据
```

`build all` 生成全部主题的安装模板，`preview all` 同时生成模板和各语言的预览数据。首次使用时，工具按 `gitea.lock.json` 准备缺失的官方文件缓存；后续使用前会校验缓存。

### 模板类型

当前 Gitea 包含以下 11 种邮件模板 [1](#注释)：

| 文件 | 通知类型 |
|---|---|
| `mail/user/auth/activate.tmpl` | 账户激活 |
| `mail/user/auth/activate_email.tmpl` | 邮箱验证 |
| `mail/user/auth/register_notify.tmpl` | 注册通知 |
| `mail/user/auth/reset_passwd.tmpl` | 密码重置 |
| `mail/org/team_invite.tmpl` | 团队邀请 |
| `mail/repo/collaborator.tmpl` | 添加仓库协作者 |
| `mail/repo/transfer.tmpl` | 仓库所有权转移 |
| `mail/repo/release.tmpl` | 发布新版本 |
| `mail/repo/actions/workflow_run.tmpl` | Actions 工作流运行 |
| `mail/repo/issue/assigned.tmpl` | 议题或合并请求指派 |
| `mail/repo/issue/default.tmpl` | 议题或合并请求动态 |

## 参与贡献

欢迎改进主题、工具、文档和翻译。[贡献指南](CONTRIBUTING.zh-CN.md)介绍了本地环境准备、设计规范、检查要求和发布流程。

## 许可证

本项目采用 [MIT 许可证](../LICENSE)。生成的发行包保留 Gitea 许可证和快照来源信息，详见[第三方声明](../THIRD_PARTY_NOTICES.md)。

---
### 注释

[1](#注释)：[Mail templates | Gitea Documentation](https://docs.gitea.com/administration/mail-templates/)

本项目与 Gitea 官方无隶属关系。