KenanZhu/GiteaMailTemplates
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

chore: refresh docs and adapt workflows for Gitea
Release / Validate Templates (push) Successful in 3m1s
Details
Release / Package & Release (push) Skipped
Details
Release / Update Latest Release Documentation (push) Skipped
Details

Browse Source
This commit is contained in:
KenanZhu committed 2026-10-09 22:02:33 +08:00
1 parent fec3ace600
commit f4d96de79e
14 files changed
+986 -505
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/CONTRIBUTING.zh-CN.md
+164 -84
View File
@@ -1,79 +1,130 @@
# 贡献指南 — Gitea 邮件模板
# 贡献指南
## 添加主题
[English](../CONTRIBUTING.md) · [项目概览](README.zh-CN.md) · [兼容性](../COMPATIBILITY.md)
1. 执行 `cd tools && go run . create <名称>`，创建共享框架主题。
2. 编辑 `themes/<名称>/theme.json` 和 `theme.css`。
3. 在 `tools/` 中运行 `go run . upstream prepare`、`go test ./...` 和 `go run . preview all`。
4. 检查英文、简体中文及另一种官方语言的桌面/移动端预览，随 PR 提交截图。
欢迎改进主题、工具、测试、文档和翻译。本指南介绍当前源码架构的开发流程；安装和版本选择请参阅 [README](README.zh-CN.md#安装)。
主题名称以小写字母开头，可包含小写字母、数字和连字符。主题只包含 `theme.json` 与 `theme.css`。新主题默认使用 `framed` 模式及 `standard` 框架布局；`layout` 选择共享框架中的结构预设。可选的 `shared` 模式仅注入 CSS，不添加框架控件。
## 本地开发
页头、操作按钮、失效提示/备用链接、侧栏和页脚统一由 `framework/mail/base/` 提供；结构预设位于 `framework/layouts/`，均属于框架，而非主题维护的邮件模板。`tools/builder/framework.go` 是唯一的官方操作值/翻译对齐层。通知分支、主题行、附件及上下文链接来自下载的官方模板，不得复制到各主题中。
## 设计规范
- 主题仅定义展示样式，共享框架使用官方邮件值与翻译组织可复用控件。
- 主题使用兼容邮件客户端的 CSS，框架负责展示结构；主题 CSS 不加载外部资源、不生成文字、不隐藏官方内容。框架引用实例托管的 Logo 是有意保留的图片引用。
- 片段校验允许展示性的 table、tr、td、div、span 等节点及展示属性，检查桌面及 390px 移动端布局。
- 尽可能测试 Gmail、Outlook、Apple Mail；浏览器预览不能模拟所有客户端的 CSS 支持。
- 忠于原主题的配色、字体、边框、页头、按钮/备用链接及布局，不使用通用卡片或新增装饰替代既有设计。
- 画廊截图使用 PNG，单张最多 50 KiB，建议 10–20 KiB。截图须来自当前源码构建，并关闭浮动信息面板。
## 更新官方快照
源码仅保留工具生成的 `gitea.lock.json`，记录稳定 Gitea 28+ 标签、不可变提交及文件校验值。官方模板、语言 JSON、图标、许可证和适配参考实现均下载到被忽略的 `build/upstream/`，不在仓库中维护副本。
### 命令参考
以下命令均在 `tools/` 执行。三个子命令都支持 `--root <仓库根目录>`，默认值为相对当前工作目录的 `..`；参数放在子命令之后，含空格的路径须加引号。
```powershell
# 在 tools/ 中显式指定仓库根目录：
go run . upstream verify --root "D:\Work\Development\WebSites\GiteaMailTemplates"
```
| 命令 | 用途 | 联网与写入行为 |
|---|---|---|
| `go run . upstream prepare` | 根据仓库锁文件准备精确匹配的输入 | 缓存不存在时按锁定提交下载，验证 SHA-256 后创建 `build/upstream/`；缓存存在时离线校验。不修改根锁文件。 |
| `go run . upstream verify` | 对照根锁文件检查已有缓存 | 离线、只读，不下载；输出 `[PASS]` 及非英文缺键的 `[FALLBACK]` 列表。 |
| `go run . upstream sync --tag vX.Y.Z` | 显式选择上游版本 | 通过 GitHub API 解析标签，按提交下载并校验快照，替换缓存并生成 `gitea.lock.json`。仅接受主版本不小于 28 的稳定 `vX.Y.Z` 标签。 |
这些命令不支持隐式 `latest`、读取本地 Gitea 克隆、令牌参数或认证环境变量。`sync` 使用 `api.github.com`，首次 `prepare` 与 `sync` 下载使用 `raw.githubusercontent.com`；网络错误与 API 限流会报错，不会自动换版本。即使快照检查离线，Go 工具链与模块仍可能需要单独联网下载。
### 已有克隆与离线使用
使用 **Go 1.24 或更高版本**。从仓库根目录开始，准备依赖和锁定的官方文件，再运行检查并生成预览：
```bash
cd tools
go mod download
go run . upstream prepare
go run . upstream verify
go test ./...
go run . preview all
```
`build all`、`preview all` 和 `dev` 会自动准备输入，但仍要求根锁文件存在。缓存完整且 Go 工具链/依赖已安装后可离线构建。`verify` 检查官方输入、适配参考实现哈希和官方英文键；框架新增键与操作锚点由构建和渲染检查，因此单独通过 `verify` 不代表兼容性验证完成。
在浏览器中打开 `preview/index.html`，或在 `tools/` 中运行 `go run . dev`，访问 [http://127.0.0.1:3456](http://127.0.0.1:3456) 使用实时预览。开发服务器监听主题、框架、锁文件与缓存、预览测试数据的变化。
CLI 使用 urfave/cli 和 x/net HTML 解析器。文档与打包检查使用 Python 3.11 或更高版本；只有浏览器检查需要 Node.js 和 `tools/qa` 中的依赖。
### 常用命令
以下命令均在 `tools/` 中执行。带有位置参数时，将选项放在位置参数之前。
| 命令 | 用途 |
|---|---|
| `go run . list` | 列出可用主题 |
| `go run . create my-theme` | 创建主题元数据和 CSS |
| `go run . build my-theme` | 生成指定主题的安装模板 |
| `go run . build all` | 生成全部主题 |
| `go run . preview all` | 构建全部主题并渲染所有官方语言 |
| `go run . dev` | 在端口 3456 启动开发服务器 |
| `go run . dev --port 3457` | 指定其他本地端口 |
| `go run . delete my-theme` | 删除指定主题的源码目录 |
`build` 将模板写入 `build/themes/<名称>/mail/`，并在 `build.json` 中记录文件和源码哈希。`preview` 同时完成构建，随后写入 `preview/rendered.js` 和 `preview/rendered/<语言>.js`。这些生成文件和下载的官方文件均被 Git 忽略，无需随贡献提交。
## 添加主题
1. 在 `tools/` 中运行 `go run . create my-theme`。
2. 编辑 `themes/my-theme/theme.json` 和 `theme.css`。
3. 在 `tools/` 中运行 `go test ./...` 和 `go run . preview all`。
4. 检查英文、简体中文及至少另一种官方语言的桌面与移动端布局，在拉取请求中附上截图。
主题名称以小写字母开头，可包含小写字母、数字和连字符。主题目录只包含 `theme.json` 和 `theme.css`。
```json
{
"name": "my-theme",
"description": "主题的简短说明",
"mode": "framed",
"layout": "standard"
}
```
| 模式 | 生成的展示结构 |
|---|---|
| `framed` | 使用共享控件和框架布局，由主题 CSS 定义样式。新主题默认使用此模式及 `standard` 布局。 |
| `shared` | 在官方页头片段中加入 CSS，并保留官方页脚片段；不增加框架控件或各类邮件的覆盖模板。 |
### 共享框架
页头、操作按钮、备用链接、侧栏和页脚位于 `framework/mail/base/`。布局预设位于 `framework/layouts/`，`framed` 主题可通过可选的 `layout` 字段选择预设。配色、字体和间距由主题 CSS 定义。
`tools/builder/framework.go` 将官方操作值和翻译键适配到共享控件。通知条件、主题行、附件和上下文链接由官方模板定义。控件或布局结构的修改应放在框架中，使各主题使用同一套适配逻辑。
布局片段组合后必须形成标签配对完整的展示结构。`__HEADER__` 插入共享页头，`__MAIL_TYPE__` 展开为发现的邮件 ID，页脚片段中的 `__SIDEBAR__` 插入共享侧栏。部署模板的 Logo 使用 `{{AppUrl}}assets/img/favicon.png`；生成的预览数据嵌入下载的图标，供离线显示。
## 设计规范
- 使用兼容邮件客户端的 CSS。主题 CSS 不得加载外部资源、生成文字或隐藏官方内容。
- 布局片段使用展示性标记。校验器接受 `table`、`tbody`、`tr`、`td`、`div`、`span` 及支持的展示属性。
- 修改已有主题时，保留其配色、字体、边框、页头、按钮和布局特征。
- 检查桌面和 390px 移动端预览，覆盖长文本和长 URL。条件允许时测试 Gmail、Outlook 和 Apple Mail；浏览器预览不能模拟邮件客户端。
- 画廊图片使用 PNG，单张不超过 50 KiB，建议为 10–20 KiB。按[截图指南](images/README.md)保持截图一致。
## 更新官方快照
`gitea.lock.json` 记录稳定的 Gitea 28+ 标签、对应提交和每个文件的 SHA-256。官方邮件模板、语言文件、图标、许可证和已评审的适配参考源码下载到 `build/upstream/`。仓库仅提交生成的根锁文件，不维护官方文件副本。
### 命令参考
在 `tools/` 中执行。每个上游子命令均支持 `--root <仓库根目录>`，默认值为相对当前工作目录的 `..`。参数放在子命令之后，包含空格的路径需要加引号：
```powershell
go run . upstream verify --root "C:\Projects\GiteaMailTemplates"
```
| 命令 | 行为 |
|---|---|
| `go run . upstream prepare` | 读取根锁文件。缓存不存在时下载并校验对应文件；已有缓存则离线校验。不修改根锁文件。 |
| `go run . upstream verify` | 对照根锁文件离线、只读检查已有缓存。输出 `[PASS]`，并以 `[FALLBACK]` 列出非英文语言缺少的键。 |
| `go run . upstream sync --tag vX.Y.Z` | 通过 GitHub API 解析明确指定的稳定 Gitea 28+ 标签，下载并校验文件，然后替换缓存并生成根锁文件。 |
`sync` 使用 `api.github.com`，文件下载使用 `raw.githubusercontent.com`。这些命令不接受本地 Gitea 克隆、认证令牌或隐式的 `latest` 版本。网络错误和 API 限流会中止操作；Go 工具链或模块可能仍需单独联网下载。
### 已有克隆与离线使用
`build`、`preview` 和 `dev` 会自动准备输入，需要已提交的根锁文件，并在使用缓存前完成校验。缓存、Go 工具链和依赖齐备后，可以离线构建。
需要单独检查缓存时，使用 `upstream verify`。它校验官方文件哈希、已评审的适配参考源码，以及官方模板引用的英文翻译键。构建和渲染还会检查框架翻译键及主要操作链接的锚点，因此缓存校验只是兼容性测试的一部分。
### 锁文件缺失与显式更新版本
缺少 `gitea.lock.json` 时，`prepare`、`verify`、构建与预览均在读取锁文件时失败，即使 `build/upstream/lock.json` 仍在也不会代用。普通源码克隆应恢复受版本控制的根锁文件；有意首次初始化时，`sync` 不要求已有根锁文件：
已有克隆缺少 `gitea.lock.json` 时，应恢复受版本控制的文件。`build/upstream/lock.json` 中的副本不能替代根锁文件。需要有意初始化锁文件时，执行：
```bash
cd tools
# 当前源码基线；显式初始化，不是发布操作：
go run . upstream sync --tag v28.0.0
go run . upstream verify
go test ./...
go run . preview all
```
评审其它版本时显式替换标签，例如此处仍为 [PENDING] 的 `v28.1.0`。检查生成的锁文件差异，对齐共享框架与测试数据，执行全部检查及同版本实例冒烟测试后，再更新兼容性文档。`sync` 不构建主题、不更新 Markdown、不创建 Git 标签、不提交、不推送，也不发布。仅缓存缺失时不应使用它。
评审其他版本时，明确指定对应标签。检查锁文件差异，按需更新框架适配逻辑和测试数据，完成检查及同版本实例冒烟测试后，再更新兼容性记录。`sync` 只修改缓存和锁文件，文档更新与版本发布需单独完成。仅缺少缓存时使用 `prepare`。
翻译或邮件渲染参考实现哈希变化会阻止同步，须先复核 Go 适配逻辑；下载新版本并不等于确认兼容。官方英文须包含官方模板引用的键，构建另行检查框架键；其它语言缺键回退英文。缓存替换前的网络/校验失败不会修改原输入。缓存替换和根锁文件写入是两个操作：文件系统错误可能留下不一致状态，后续校验会失败，重试前先检查二者。
已评审的翻译或邮件渲染参考源码发生变化时，须先评审适配逻辑，再更新参考哈希。官方英文必须包含所有引用的翻译键；其他语言缺少的翻译回退为英文。新增邮件类型需要补充框架适配和 `tools/data/templates_config.json` 中的测试数据，该文件提供预览元数据和示例上下文。JSON 测试数据中的整数应保持整数形式，以便 Go 正确格式化。
缓存替换前发生网络或校验错误时，原有文件保持不变。缓存替换和根锁文件写入是两个操作；文件系统错误中断操作后，重试前应检查二者是否一致。
### 缓存恢复
`prepare` 拒绝损坏、不完整或锁文件不匹配的缓存，不合并、不静默修复；`sync` 也拒绝替换非空的无效快照。检查错误后，将精确的生成缓存目录移到备份位置，再按已复核的根锁文件执行 `prepare`。例如在 **仓库根目录的 PowerShell** 中，选择尚不存在的备份名称：
`prepare` 会报告损坏、不完整或与锁文件不匹配的缓存，不会自动修复。`sync` 同样拒绝替换非空的无效快照。检查错误后，将生成的缓存移至备份位置，再按已评审的根锁文件重新准备。
例如，在**仓库根目录的 PowerShell** 中，使用尚不存在的备份名称：
```powershell
Move-Item -LiteralPath .\build\upstream -Destination .\build\upstream.backup
@@ -82,58 +133,87 @@ go run . upstream prepare
go run . upstream verify
```
不要删除整个 `build/` 或修改缓存中的官方文件。显式同步后如需回退，恢复之前已复核的根锁文件，再按同样方式重建缓存。避免多个 `sync`/`prepare`/构建进程同时操作同一缓存；替换输入前先停止 `dev`。
保留 `build/` 中的其他内容，不直接编辑缓存中的官方文件。需要回退快照时，恢复此前已评审的根锁文件，再按同样方式重建缓存。替换输入前先停止 `dev`，避免多个进程同时写入同一缓存。
邮件类型由快照发现，`tools/data/templates_config.json` 仅提供名称、描述和模拟上下文。新增官方邮件类型后，必须补充测试数据才能通过预览校验。
### 已知上游格式问题
Gitea v28.0.0 的波兰语 `mail.team_invite.text_1` 存在已确认的占位符缺陷。预览保留官方行为并报告 `[UPSTREAM-WARN]`，例外严格匹配官方原文。其他格式错误会使渲染失败。不要直接修改语言快照来隐藏官方问题。
## 本地开发
使用 **Go 1.24+**。CLI 依赖 urfave/cli，HTML 校验使用 Go 的 x/net 解析器。先执行 `go mod download` 和 `upstream prepare` 下载依赖及锁定输入，之后可离线构建。
```bash
cd tools
go run . list
go run . build all
go run . preview all
go run . dev
# http://127.0.0.1:3456
```
`build` 将安装文件写入 `build/themes/<名称>/mail/`。`preview` 同时完成构建，生成小型清单和每种官方语言各自的 JS 数据包。直接打开 `preview/index.html` 即可静态预览，语言加载支持 `file://`。
回环开发服务器监听主题 CSS/元数据、共享框架、锁文件/缓存和测试数据，通过 SSE 刷新。安装模板的 Logo 引用 `{{AppUrl}}assets/img/favicon.png`；仅静态预览的生成数据嵌入下载的官方图标，以支持离线显示。
Gitea v28.0.0 的波兰语 `mail.team_invite.text_1` 存在占位符缺陷。预览保留官方输出并报告 `[UPSTREAM-WARN]`。该例外仅匹配已评审的完整原文，其他格式错误会使渲染失败。发现上游问题时应报告问题，不修改缓存中的语言文件。
## 验证与发布
测试检查框架适配与生成的确定性、操作锚点变化时失败、官方翻译键及通知语义保留。渲染覆盖全部主题/语言及推送、评审、回复、工作流和附件分支。控件及品牌区域是明确的展示增补；按钮文字、备用链接目标和 Logo 引用单独校验。
### 拉取请求检查
发布前，在与快照标签一致的隔离 Gitea 实例中触发真实的密码重置或通知邮件。管理后台的测试邮件按钮不会使用自定义模板。确认模板加载并捕获邮件，避免向真实用户发送测试内容。
在 `tools/` 中运行 `go test ./...` 和 `go run . preview all`。测试覆盖生成结果的确定性、操作锚点变化、翻译键，以及全部主题和语言的通知主题行、正文与链接。测试数据包含推送、评审、回复、工作流和附件分支；共享控件与品牌展示作为附加内容单独处理。
可选的 `tools/integration` 测试使用临时 SQLite、用户、Git/SSH 路径及回环 SMTP 自动完成此流程。将 `GITEA_SMOKE_BINARY` 设为已校验官方 SHA-256、版本与快照一致的 Gitea 可执行文件，在 `tools/` 执行 `go test ./integration -v -count=1`。浏览器检查位于 `tools/qa`：生成预览后安装其可选依赖并运行 `npm test`；设置 `PREVIEW_DEV_URL` 可同时检查 HTTP 预览，`--update-gallery` 可更新截图。
修改文档、追踪脚本或打包流程时，在仓库根目录执行：
发行标签须与快照中的 Gitea 版本一致，在 `.github/release-notes/vX.Y.Z.md` 添加已复核的说明。工作流校验快照和测试，打包生成主题、多语言预览、文档及官方许可证/来源信息，再更新发布标签区块。源码修改与已发布兼容矩阵保持区分；历史标签和附件不变。
```bash
python -B -m unittest discover -s .github/scripts -p 'test_*.py'
```
手动打包时，先执行 `preview all`，再从仓库根目录运行 `python .github/scripts/package_release.py --version vX.Y.Z --output <新输出目录>`。发布工作流使用同一脚本；它校验源码/产物哈希和全部语言包，排除未声明的旧构建目录，并拒绝覆盖已有压缩包。
调整通用说明时，同步更新英文和简体中文指南。拉取请求应说明改动内容及相关检查结果，涉及视觉变化时附上截图。
### 浏览器与 Gitea 实例检查
生成预览数据后，可运行浏览器检查：
```bash
cd tools/qa
npm install
npx playwright install chromium
npm test
```
如需使用已安装的 Chrome 或 Edge，设置 `BROWSER_EXECUTABLE_PATH`，无需再安装 Chromium。设置 `PREVIEW_DEV_URL` 可同时检查运行中的 HTTP 预览。`npm test -- --update-gallery` 会一并更新画廊截图。
发布前，在与锁定版本一致的隔离 Gitea 实例中加载生成的模板，捕获真实的密码重置或通知邮件。管理后台的测试邮件按钮不使用自定义模板。
可选的 `tools/integration` 测试使用临时 SQLite 数据、用户、Git/SSH 路径和回环 SMTP。将 `GITEA_SMOKE_BINARY` 设为已校验官方校验值、版本与锁文件一致的 Gitea 可执行文件，再在 `tools/` 中运行 `go test ./integration -v -count=1`。邮件仅在本地捕获，不发送给真实用户。未设置该变量时会跳过此测试。发布工作流不会自动运行可选的浏览器和真实 Gitea 实例检查。
### 准备发行版
发行标签必须与锁定的 Gitea 版本一致。当前源码重构尚未发布，已有 v28.0.0 和历史版本的附件应保留。
1. 完成自动化检查、预览检查和同版本实例冒烟测试。
2. 在 `.github/release-notes/vX.Y.Z.md` 添加已评审的发行说明，并按验证结果更新兼容性记录。
3. 在 `tools/` 中运行 `go run . preview all`，生成全部主题和语言数据。
4. 打包并检查发行包内容后再发布。
手动打包时，在仓库根目录执行：
```bash
python .github/scripts/package_release.py --version vX.Y.Z --output <new-output-directory>
```
将版本和输出目录占位符替换为已评审的标签及新的目录。脚本会检查源码与产物哈希，包含所有语言数据包，排除残留的旧主题构建，并拒绝覆盖已有压缩包。
发布工作流使用同一脚本打包模板、预览、文档、官方许可证和来源信息，并更新受管理的版本标记。依赖自动发布前，请确认所用 Gitea 主机的 Actions 支持和写入权限。Markdown 管理区块的说明见[版本追踪](../COMPATIBILITY.md#version-tracking)。
### Gitea 工作流配置
两个工作流均使用 `linux-amd64-docker-small` Runner 标签。任务镜像需要支持检出和工具链安装步骤使用的 Node.js Action，并提供 Git 和 POSIX Shell。Go 与 Python 由安装步骤准备。
PR 创建和发行附件上传通过 `.github/scripts/gitea_actions.py` 调用实例的 `/api/v1` API。工作流传入实例地址、仓库名称和内置 `GITEA_TOKEN`，仓库设置需要允许所请求的代码、发行版及拉取请求写入权限。可选的 `UPSTREAM_GITHUB_TOKEN` Secret 仅用于查询 GitHub 上的官方发行版；未配置时使用 GitHub 的匿名 API 限额。
追踪工作流会复用内容相同的已有分支及对应的未关闭 PR。分支内容不同时需要人工检查，工作流不会强制推送。发布流程拒绝修改任何已有发行版，包括草稿；新版本在两个压缩包上传成功后才从草稿转为发布状态。上传失败时，重试前先检查草稿；已发布版本及附件应保持不变。
## 报告问题
注明快照标签/提交、主题、邮件类型、预览语言和错误。先运行 `go run . upstream verify` 与 `go run . preview all`，附上截图或渲染诊断。
请提供 Gitea 版本、模板发行版或源码提交、主题、邮件类型、语言和复现步骤。源码构建问题还应包含快照标签与提交，以及 `go run . upstream verify` 或 `go run . preview all` 的输出。显示问题请注明邮件客户端，并附上移除个人信息后的截图。
## 提交规范
- `style(<名称>):` — 主题展示样式
- `preview:` — 浏览器预览
- `tools:` — CLI、构建及快照工具
- `docs:` — 文档和翻译
- `fix:` — 修复
- `refactor:` — 重构
- `chore:` — 维护
| 前缀 | 范围 |
|---|---|
| `style(<名称>):` | 主题展示样式 |
| `preview:` | 浏览器预览 |
| `tools:` | CLI、构建与快照工具 |
| `docs:` | 文档和翻译 |
| `fix:` | 问题修复 |
| `project:` | 仓库配置和项目结构 |
| `refactor:` | 代码重构 |
| `chore:` | 日常维护 |
## 翻译与许可证
- [English CONTRIBUTING](../CONTRIBUTING.md)
- 简体中文（本文）
贡献以 MIT 许可证授权，分发派生模板时须保留 Gitea 版权及官方许可证。
[英文指南](../CONTRIBUTING.md)介绍相同的开发流程。贡献采用 MIT 许可证；分发派生模板时，请保留 Gitea 版权和官方许可证，详见[第三方声明](../THIRD_PARTY_NOTICES.md)。
docs/README.zh-CN.md
+113 -67
View File
@@ -1,48 +1,47 @@
# Gitea 邮件模板
<!-- DOC-TAGS: {"TRACKER":["LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
为自托管 [Gitea](https://about.gitea.com) 提供精心设计、可直接部署的多风格邮件模板。
为自托管 [Gitea](https://about.gitea.com) 提供邮件主题、本地预览和自定义邮件模板构建工具。
[English](../README.md) · [安装](#安装) · [预览](#预览) · [兼容性](../COMPATIBILITY.md) · [贡献指南](CONTRIBUTING.zh-CN.md)
<!-- RELEASE:HEADER -->
> 最新发布版：[v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
<!-- /RELEASE:HEADER -->
---
仓库包含十种主题，覆盖账户、仓库、议题和工作流等邮件通知。通知内容和翻译由 Gitea 提供，主题负责展示样式。
## 设计理念
大多数自托管 Gitea 实例使用默认的纯文本邮件模板。本项目提供了**开箱即用、视觉精美的替代方案**——每种方案都针对特定社区或受众设计，您可以选择最适合您用户的风格。
`main` 分支使用锁定的官方输入及共享控件框架：Gitea 提供邮件值、通知逻辑与翻译，框架负责页头、按钮、备用链接和页脚，主题仅定义样式。官方文件在开发/CI 时下载，不在仓库中维护副本。该重构尚未发布，以 v28.0.0 为基线；源码克隆需先构建安装文件，发行包提供可直接复制的产物。使用已发布版本前，请查看[兼容性说明](../COMPATIBILITY.md)。
---
`main` 分支的源码架构**尚未发布**，以 Gitea v28.0.0 为基线，通过锁定的官方文件和共享布局框架构建模板。已发布的压缩包保留原有内容和兼容范围。安装前，请根据 Gitea 版本查阅[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)，选择对应的发行包。
## 风格画廊
下表展示仓库当前收录的主题；新增主题可作为独立目录放在 `themes/` 下，不受现有数量限制。
| 预览 | 主题 | 样式特点 |
|---|---|---|
| ![Horizon](images/horizon.png) | **Horizon** | 蓝色强调色、灰色文字、居中白色卡片 |
| ![Terminal](images/terminal.png) | **Terminal** | 深色背景、等宽字体、绿色强调色 |
| ![Ember](images/ember.png) | **Ember** | 暖橙色调、衬线标题、圆角按钮 |
| ![Bloom](images/bloom.png) | **Bloom** | 浅蓝色渐变、圆角卡片与按钮 |
| ![Heritage](images/heritage.png) | **Heritage** | 藏蓝与金色、双线边框、衬线字体 |
| ![Neon](images/neon.png) | **Neon** | 深色背景、粉红与青色、发光效果 |
| ![Mono](images/mono.png) | **Mono** | 黑白配色、红色强调色、直角边框 |
| ![Terra](images/terra.png) | **Terra** | 大地色调、陶土色按钮、衬线字体 |
| ![Ink](images/ink.png) | **Ink** | 报刊式布局、侧栏、衬线字体与首字下沉 |
| ![Aurora](images/aurora.png) | **Aurora** | 深紫色背景、青绿色强调色、柔和光晕 |
| 预览 | 风格 | 受众 | 特点 |
|---|---|---|---|
| ![Horizon](images/horizon.png) | **Horizon** | 企业/公司 | 蓝色强调色、石板灰排版、居中卡片 |
| ![Terminal](images/terminal.png) | **Terminal** | 开发者/技术 | 暗色模式、等宽字体、绿色命令行风格 |
| ![Ember](images/ember.png) | **Ember** | 社区/开源 | 暖琥珀色、圆角、人文主义、包容 |
| ![Bloom](images/bloom.png) | **Bloom** | 创意/初创 | 蓝色玻璃卡片、柔和渐变、圆角按钮 |
| ![Heritage](images/heritage.png) | **Heritage** | 教育/研究 | 纸质色调、海军蓝与金色、双线边框、衬线字体 |
| ![Neon](images/neon.png) | **Neon** | 游戏/Web3/创意科技 | 赛博朋克霓虹、粉红与青色、合成波能量 |
| ![Mono](images/mono.png) | **Mono** | 设计工作室/编辑 | 瑞士粗野主义、黑白红强调、零圆角 |
| ![Terra](images/terra.png) | **Terra** | 可持续/健康 | 大地色、陶土色按钮、自然风格细节、柔和卡片 |
| ![Ink](images/ink.png) | **Ink** | 出版/新闻/文学 | 报刊分栏、海军蓝与金色分隔线、衬线字体及首字下沉 |
| ![Aurora](images/aurora.png) | **Aurora** | 高端SaaS/正念 | 空灵光效渐变、深紫与青绿、大气光晕 |
> 画廊展示共享框架的当前源码构建，并非历史发行包。保留原主题的配色、字体、页头及按钮/备用链接控件。查看[本地预览](../preview/index.html)及[截图说明](images/README.md)。
[**本地预览画廊**](../preview/index.html) — 先按下文生成预览数据，再在浏览器中打开。
---
截图展示当前源码的构建结果。其他邮件类型和语言可通过[本地预览](#预览)查看；更新截图请参阅[截图指南](images/README.md)。
## 安装
源码克隆需按仓库提交的 `gitea.lock.json` 先构建（Go 1.24+，缓存不存在时首次构建下载锁定输入）。锁文件缺失会报错，不会自动选择最新版 Gitea：
### 选择安装来源
运行 `gitea --version` 确认实例版本，再按[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)选择模板版本。
| 来源 | 邮件模板目录 | 准备步骤 |
|---|---|---|
| 发行压缩包 | `themes/<名称>/mail/` | 下载并解压推荐版本的发行包 |
| 源码仓库 | `build/themes/<名称>/mail/` | 使用 Go 1.24 或更高版本构建 |
从源码构建时，在仓库根目录执行：
```bash
cd tools
@@ -50,37 +49,45 @@ go run . build all
cd ..
```
选择一种风格，将生成的 `mail/` 目录复制到 Gitea 自定义模板路径。发行压缩包中的路径为 `themes/<名称>/mail/`，源码构建后的路径为 `build/themes/<名称>/mail/`：
缓存不存在时，首次构建会下载 `gitea.lock.json` 锁定的官方文件；后续构建会先校验缓存。构建需要根目录的锁文件，文件缺失或缓存损坏的处理方式见[准备与恢复说明](CONTRIBUTING.zh-CN.md#更新官方快照)。
### 安装主题
将所选主题 `mail/` 目录中的内容复制到 `<GITEA_CUSTOM>/templates/mail/`，然后重启 Gitea。复制前请确认实例实际使用的自定义目录。以下是常见部署路径示例：
| 部署方式 | 自定义目录示例 |
|---|---|
| Linux 二进制部署 | `/var/lib/gitea/custom` |
| Docker | `/data/gitea` |
| Windows | `C:\gitea\custom` |
例如，在使用 systemd 管理 Gitea 的 Linux 主机上，从已解压的发行包目录执行：
```bash
mkdir -p /var/lib/gitea/custom/templates/mail
cp -r build/themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
systemctl restart gitea
```
切换前备份当前邮件覆盖文件，根据上一主题的 `build.json` 移除其安装文件，再复制新主题完整输出；保留其他自定义模板。从 `framed` 切换到 `shared` 时，遗留的正文覆盖文件仍会使用旧布局，因此不能仅覆盖两个共享片段。
使用源码构建产物时，将复制来源改为 `build/themes/horizon/mail/.`。Docker 和 Windows 部署请使用相应的容器或服务管理方式重启。
请确认实例实际配置的自定义目录再安装；常见部署示例为 Linux 二进制部署的 `/var/lib/gitea/custom`、Docker 的 `/data/gitea`，以及 Windows 的 `C:\gitea\custom`，这些并非所有实例的统一默认路径。
### 切换主题
先备份已有邮件模板，再移除上一主题安装的文件，复制新主题的完整产物。当前源码构建会在 `build.json` 中记录生成的文件；历史发行包可参照压缩包内容确认文件范围。保留其他自定义模板。
从 `framed` 切换到 `shared` 模式时，尤其需要清理旧主题文件，否则残留的覆盖模板可能继续使用原有布局。
### 确认生效
管理后台的测试邮件不会使用自定义模板。要验证模板是否生效，请触发一次真实的
邮件通知。最快的方式是密码重置：退出登录，点击登录页的**"忘记密码"**，查看
重置邮件即可——它将使用你的自定义样式渲染。
---
使用测试账户触发密码重置等邮件通知，检查邮件样式和链接。管理后台的测试邮件按钮不使用自定义邮件模板。
## 预览
源码克隆需先生成被忽略的 `preview/rendered.js` 清单及逐语言数据包。后续发行包会包含全部官方语言的预览，现有 v28.0.0 及更早压缩包保持原内容。
预览支持切换主题、邮件类型和语言，查看渲染结果或 HTML 源码，切换桌面与移动端视口，以及查看示例数据面板。v28.0.0 快照包含 11 种邮件类型和 28 种语言。
### 官方输入命令（`upstream`）
### 静态预览
在 `tools/` 执行：`go run . upstream prepare` 根据已有锁文件下载尚不存在的缓存；`go run . upstream verify` 离线校验已有缓存；`go run . upstream sync --tag vX.Y.Z` 显式替换版本并生成锁文件。均支持子命令后的 `--root <仓库根目录>`，默认 `..`。
缺少根锁文件时，准备、校验、构建与预览都会失败。普通克隆应恢复受版本控制的锁文件；有意初始化可运行 `go run . upstream sync --tag v28.0.0`。同步须联网，仅接受稳定 Gitea 28+ 标签，不更新文档或发布版本。损坏/版本不匹配的缓存需要检查后恢复，而非自动修复，详见[完整命令与恢复指南](CONTRIBUTING.zh-CN.md#更新官方快照)。
**静态模式：**
在源码仓库中生成预览数据：
```bash
cd tools
@@ -88,56 +95,95 @@ go run . preview all
cd ..
```
然后在浏览器中打开 `preview/index.html`，无需启动服务器。
在浏览器中打开 [preview/index.html](../preview/index.html)。语言数据按需加载，支持 `file://`，无需启动服务器。当前打包脚本生成的发行包包含这些数据；历史发行包保留其原有预览内容。
**开发服务器（实时重载）：**
### 开发服务器
```bash
cd tools
go run . dev
# 在浏览器中打开 http://127.0.0.1:3456
```
| 功能 | 静态 | Dev |
|-----------|--------|-----|
| Go 模板渲染 | [YES] | [YES] |
| 主题/模板/语言切换 | [YES] | [YES] |
| 实时重载 | [NO] | [YES] |
打开 [http://127.0.0.1:3456](http://127.0.0.1:3456)。Go 服务器监听主题文件、共享框架、锁文件与缓存、预览测试数据的变化，重新构建后通过服务器发送事件（SSE）刷新页面。
预览支持主题、邮件类型及全部官方语言切换（v28.0.0 快照含 28 种语言），以及 Modern/Source 视图、桌面/移动端尺寸和参数面板。语言数据按需加载，支持直接打开本地文件。`←→` 可切换选择框，`↑↓` 可切换选项，`d`/`m` 可切换视口。
| 控件 | 选项或快捷键 |
|---|---|
| 主题、模板、语言和视图 | `←` / `→` 切换选择框，`↑` / `↓` 选择选项 |
| 视图 | **Modern** 显示渲染结果，**Source** 显示生成的 HTML 文本 |
| 视口 | **Desktop**（1386 × 780）、**Mobile**（390 × 780）；快捷键 `d` / `m` |
| 信息面板 | `p` 展开或收起面板 |
---
预览使用示例数据渲染模板。浏览器与邮件客户端对 CSS 的支持不同，部署前还需在目标邮件客户端中检查效果。
## 兼容性
- **Gitea 28.0.0** — 使用模板发布版 v28.0.0；旧版 Gitea 请选用对应的旧版模板
<!-- TRACKER:LATEST-TESTED -->
- **最新测试：** Gitea 28.0.0
<!-- /TRACKER:LATEST-TESTED -->
<!-- RELEASE:SUMMARY -->
- **最新发布版：** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
<!-- /RELEASE:SUMMARY -->
- 其它 Gitea 版本请先查看[逐版本兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)再选择模板压缩包；标记为 [PENDING] 的版本尚无已验证的推荐包。版本号相符的 v1.27.2 存在已知的推送通知问题。
<!-- TRACKER:UPSTREAM -->
- **上游 Gitea 28.1.0：** [PENDING]
<!-- /TRACKER:UPSTREAM -->
- 新源码架构支持 Gitea 28+，离线校验官方快照；源码状态及历史发行版限制详见[兼容性说明](../COMPATIBILITY.md)。
## 模板类型
当前源码架构面向 Gitea 28 及更高版本，兼容性按锁定版本验证。新的上游版本在完成评审前保持待验证状态。早期 Gitea 版本请使用[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)推荐的发行包；其中也记录了 v1.27.2 推送通知修复不完整的问题。
邮件类型由官方输入发现，当前为 11 种：账户激活、邮箱验证、注册通知、密码重置、团队邀请、仓库协作者、仓库转移、新版发布、Actions 工作流、议题/合并请求指派及议题/合并请求更新。具体路径参见[英文 README](../README.md#template-types)。`framed` 主题使用同一对齐层与共享控件生成安装文件；可选的 `shared` 模式仅覆盖两个基础片段，不添加框架控件。
生成的模板使用 Gitea 内置函数和官方翻译键，缺少的翻译回退为英文。锁定的 v28.0.0 语言文件存在已知的波兰语邀请文案格式缺陷，预览会报告 `[UPSTREAM-WARN]` 并保留官方输出。详见[已知限制](../COMPATIBILITY.md#snapshot-driven-source-status)。
## 设计与翻译
## 目录结构
主题仅维护 CSS 与元数据；共享框架使用官方邮件值及翻译组织可复用控件，保留通知条件、主题行和功能链接目标。官方模板及语言文件下载到忽略的 `build/upstream/`，仅提交工具生成的 `gitea.lock.json`。语言缺键按 Gitea 规则回退英文。v28.0.0 波兰语邀请文案存在官方占位符缺陷，预览报告 `[UPSTREAM-WARN]` 并保留官方行为，详见[贡献指南](CONTRIBUTING.zh-CN.md#更新官方快照)。
```text
gitea.lock.json # 官方标签、提交和文件校验值
framework/ # 共享邮件控件和布局预设
themes/<名称>/ # 主题元数据（theme.json）和样式（theme.css）
tools/ # Go 命令行工具、构建工具和测试
cli/ # 命令定义
upstream/ # 快照下载、校验和翻译键发现
builder/ # 官方模板适配与主题生成
preview/ # 邮件渲染、语言适配和开发服务器
config/, data/ # 预览元数据和示例上下文
integration/, qa/ # 可选的 Gitea 实例与浏览器检查
preview/ # 浏览器界面；生成的清单和语言数据包
docs/ # 简体中文指南和画廊图片
.github/ # 工作流、发行说明、打包与版本追踪脚本
build/upstream/ # 下载的官方文件，不纳入版本控制
build/themes/ # 生成的安装模板，不纳入版本控制
```
## 文档与贡献
官方模板定义通知数据、条件、主题行和 URL。共享框架将其组织为页头、操作按钮、备用链接和页脚，主题定义配色、字体与间距。`framed` 和 `shared` 模式的说明见[主题开发指南](CONTRIBUTING.zh-CN.md#添加主题)。
### 模板类型
邮件类型从锁定的快照中发现。v28.0.0 的邮件入口如下：
| 文件 | 通知类型 |
|---|---|
| `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)介绍了本地环境准备、设计规范、检查要求和发布流程。
## 相关文档
- [English README](../README.md)
- [简体中文 README](README.zh-CN.md)
- [English CONTRIBUTING](../CONTRIBUTING.md)
- [简体中文贡献指南](CONTRIBUTING.zh-CN.md)
- [简体中文贡献指南](CONTRIBUTING.zh-CN.md) · [English contributor guide](../CONTRIBUTING.md)
- [兼容性与模板参考](../COMPATIBILITY.md)
- [画廊截图指南](images/README.md)
## 许可证
MIT — 详见 [LICENSE](../LICENSE) 和[第三方声明](../THIRD_PARTY_NOTICES.md)。发行包保留官方 Gitea 许可证和快照来源信息。
本项目采用 [MIT 许可证](../LICENSE)。生成的发行包保留 Gitea 许可证和快照来源信息，详见[第三方声明](../THIRD_PARTY_NOTICES.md)。
本项目与 Gitea 官方无隶属关系。
docs/images/README.md
+34 -21
View File
@@ -1,31 +1,44 @@
# Style Preview Images
# Gallery Images
> Images show the current snapshot-driven source build. Historical release archives retain their original templates and are not replaced by these screenshots.
Gallery images show the current source build. Historical release archives retain their original templates.
Place theme style screenshots of **Desktop** in PNG format here, captured from the [local preview](../../preview/index.html).
## Capture Settings
## Naming Convention
Use the same settings for every theme so images remain comparable:
```
horizon.png terminal.png ember.png bloom.png heritage.png
neon.png mono.png terra.png ink.png aurora.png
| Setting | Value |
|---|---|
| Template | **Register Notify** |
| Language | **en-US** |
| View | **Modern** |
| Viewport | **Desktop** |
| Information panel | Collapsed |
| Output | PNG, 600px wide recommended |
Save images as `<theme-name>.png` in this directory, matching the directory name under `themes/`. Each file must be at most **50 KiB**; **10–20 KiB** is preferred. Optimize larger PNGs with tools such as `pngquant` or `optipng`.
## Automated Capture
Generate preview data from the repository root:
```bash
cd tools
go run . preview all
cd qa
npm install
npx playwright install chromium
npm test -- --update-gallery
```
## Image Size Requirements
To use installed Chrome or Edge, set `BROWSER_EXECUTABLE_PATH` instead of installing Chromium. The script checks language loading, controls and mobile overflow, saves captures in `build/screenshots/`, then copies them here after enforcing the size limit. Review the resulting images before committing.
To ensure screenshots can be displayed in the README, please follow these size requirements:
Run `npm test` without `--update-gallery` to perform the checks and capture images without changing the committed gallery.
- **Maximum:** 50 KiB per image
- **Recommended:** 10–20 KiB
- **Format:** PNG, optimised — run through `pngquant` or `optipng` before committing
## Manual Capture
## How to Capture
1. Run `go run . dev` from `tools/` and open [http://127.0.0.1:3456](http://127.0.0.1:3456). Alternatively, run `go run . preview all` and open [preview/index.html](../../preview/index.html) directly.
2. Select a theme and apply the capture settings above.
3. Capture the rendered email, excluding the preview toolbar and information panel.
4. Save the PNG as `<theme-name>.png`, check its size and repeat for the remaining themes.
1. Start the dev server: `cd tools && go run . dev` and open http://127.0.0.1:3456 in your browser
2. For each style, select the **"Register Notify"** template and **"Modern"** view, **"en-US"** language and **"Desktop"** viewport; close the floating inspector
3. Take a screenshot of the rendered email (600px width recommended)
4. Save as `<style-name>.png` in this directory
> For a source clone, run `cd tools && go run . preview all`, return to the repository root, then open `preview/index.html` directly.
For automated capture, install the optional dependencies in `tools/qa` and run `node preview.cjs --update-gallery` there. Set `BROWSER_EXECUTABLE_PATH` when using an installed Chrome/Edge instead of Playwright's bundled Chromium.
When adding a theme, update its gallery entry in both the [English README](../../README.md#style-gallery) and [Simplified Chinese README](../README.zh-CN.md#风格画廊).