chore: simplify workflows and unify tool logging and mail presentation
This commit is contained in:
KenanZhu committed
1 parent
f4d96de79e
commit
c93f2bf8b2
40 files changed
+523
-1515
No files matched your search
+91
-71
@@ -1,93 +1,96 @@
|
||||
# Gitea 邮件模板
|
||||
<!-- DOC-TAGS: {"TRACKER":["LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
|
||||
# Gitea Mail Template
|
||||
---
|
||||
|
||||
为自托管 [Gitea](https://about.gitea.com) 提供邮件主题、本地预览和自定义邮件模板构建工具。
|
||||
[English](../README.md)
|
||||
|
||||
[English](../README.md) · [安装](#安装) · [预览](#预览) · [兼容性](../COMPATIBILITY.md) · [贡献指南](CONTRIBUTING.zh-CN.md)
|
||||
Gitea Mail Template 为自托管的 [Gitea](https://about.gitea.com) 提供多种可选、适合的邮件模板风格。
|
||||
|
||||
<!-- RELEASE:HEADER -->
|
||||
> 最新发布版：[v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
|
||||
<!-- /RELEASE:HEADER -->
|
||||
|
||||
仓库包含十种主题，覆盖账户、仓库、议题和工作流等邮件通知。通知内容和翻译由 Gitea 提供，主题负责展示样式。
|
||||
|
||||
`main` 分支的源码架构**尚未发布**，以 Gitea v28.0.0 为基线，通过锁定的官方文件和共享布局框架构建模板。已发布的压缩包保留原有内容和兼容范围。安装前，请根据 Gitea 版本查阅[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)，选择对应的发行包。
|
||||
仓库包含数种主题的 Gitea 邮件模板，适合大多数的部署场景与应用范围。安装前，请根据 Gitea 版本查阅[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)，选择对应的发行包。
|
||||
|
||||
## 风格画廊
|
||||
|
||||
这里展示邮件模板通过预览工具呈现的实际渲染风格和效果。
|
||||
|
||||
| 预览 | 主题 | 样式特点 |
|
||||
|---|---|---|
|
||||
|  | **Horizon** | 蓝色强调色、灰色文字、居中白色卡片 |
|
||||
|  | **Terminal** | 深色背景、等宽字体、绿色强调色 |
|
||||
|  | **Ember** | 暖橙色调、衬线标题、圆角按钮 |
|
||||
|  | **Bloom** | 浅蓝色渐变、圆角卡片与按钮 |
|
||||
|  | **Heritage** | 藏蓝与金色、双线边框、衬线字体 |
|
||||
|  | **Neon** | 深色背景、粉红与青色、发光效果 |
|
||||
|  | **Mono** | 黑白配色、红色强调色、直角边框 |
|
||||
|  | **Terra** | 大地色调、陶土色按钮、衬线字体 |
|
||||
|  | **Ink** | 报刊式布局、侧栏、衬线字体与首字下沉 |
|
||||
|  | **Aurora** | 深紫色背景、青绿色强调色、柔和光晕 |
|
||||
|  | **Bloom** | 浅蓝色渐变、圆角卡片与按钮 |
|
||||
|  | **Ember** | 暖橙色调、衬线标题、圆角按钮 |
|
||||
|  | **Heritage** | 藏蓝与金色、双线边框、衬线字体 |
|
||||
|  | **Horizon** | 蓝色强调色、灰色文字、居中白色卡片 |
|
||||
|  | **Ink** | 报刊式布局、侧栏、衬线字体与首字下沉 |
|
||||
|  | **Mono** | 黑白配色、红色强调色、直角边框 |
|
||||
|  | **Neon** | 深色背景、粉红与青色、发光效果 |
|
||||
|  | **Terminal** | 深色背景、等宽字体、绿色强调色 |
|
||||
|  | **Terra** | 大地色调、陶土色按钮、衬线字体 |
|
||||
|
||||
截图展示当前源码的构建结果。其他邮件类型和语言可通过[本地预览](#预览)查看；更新截图请参阅[截图指南](images/README.md)。
|
||||
截图仅展示当前默认构建效果，其他邮件类型和语言可通过[本地预览](#预览)查看；更新截图请参阅[截图指南](images/README.md)。
|
||||
|
||||
## 安装
|
||||
|
||||
### 选择安装来源
|
||||
|
||||
运行 `gitea --version` 确认实例版本，再按[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)选择模板版本。
|
||||
运行 `gitea --version` 确认部署的 Gitea 实例版本，再按照[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)选择模板版本。
|
||||
|
||||
> [!WARNING]
|
||||
> 我们不建议直接从源码仓库拉取并构建，因为这些版本还未经过完全测试达到发行可用的水平。如果存在未知的模板参数过时或遗漏可能导致 Gitea 实例启动异常。
|
||||
|
||||
> [!TIP]
|
||||
> 如果仍然需要从源码构建邮件模板，下方同样给出的相应步骤方法。
|
||||
|
||||
| 来源 | 邮件模板目录 | 准备步骤 |
|
||||
|---|---|---|
|
||||
| 发行压缩包 | `themes/<名称>/mail/` | 下载并解压推荐版本的发行包 |
|
||||
| 源码仓库 | `build/themes/<名称>/mail/` | 使用 Go 1.24 或更高版本构建 |
|
||||
| 发行版 | `themes/<名称>/mail/` | 下载并解压推荐版本的发行包 |
|
||||
| 源码 | `build/themes/<名称>/mail/` | 使用 Go 1.24 或更高版本构建 |
|
||||
|
||||
从源码构建时，在仓库根目录执行：
|
||||
从源码构建时，请在仓库根目录执行：
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
go run . build all
|
||||
cd ..
|
||||
```
|
||||
|
||||
缓存不存在时，首次构建会下载 `gitea.lock.json` 锁定的官方文件；后续构建会先校验缓存。构建需要根目录的锁文件，文件缺失或缓存损坏的处理方式见[准备与恢复说明](CONTRIBUTING.zh-CN.md#更新官方快照)。
|
||||
构建可用模板时需要依赖于 Gitea 官方仓库的资源文件，以确保来源的一致性。因此该命令会自动下载由`gitea.lock.json` 文件锁定的官方文件，后续构建无需再次下载，使用缓存目录资源即可运行。文件缺失或缓存损坏的处理方式见[更新官方快照](CONTRIBUTING.zh-CN.md#更新官方快照)。
|
||||
|
||||
### 安装主题
|
||||
|
||||
将所选主题 `mail/` 目录中的内容复制到 `<GITEA_CUSTOM>/templates/mail/`，然后重启 Gitea。复制前请确认实例实际使用的自定义目录。以下是常见部署路径示例：
|
||||
将所选主题 `mail/` 目录中的内容复制到 `<GITEA_CUSTOM>/templates/mail/`，然后重启 Gitea 即可生效。复制前请确认实例实际使用的自定义目录。以下是常见部署路径示例：
|
||||
|
||||
| 部署方式 | 自定义目录示例 |
|
||||
|---|---|
|
||||
| Linux 二进制部署 | `/var/lib/gitea/custom` |
|
||||
| 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
|
||||
```
|
||||
|
||||
使用源码构建产物时，将复制来源改为 `build/themes/horizon/mail/.`。Docker 和 Windows 部署请使用相应的容器或服务管理方式重启。
|
||||
> [!TIP]
|
||||
> 使用源码构建产物时，将复制来源改为 `build/themes/horizon/mail/.`。Docker 和 Windows 部署请使> 用相应的容器或服务管理方式暂停和重启。
|
||||
|
||||
### 切换主题
|
||||
|
||||
先备份已有邮件模板，再移除上一主题安装的文件，复制新主题的完整产物。当前源码构建会在 `build.json` 中记录生成的文件；历史发行包可参照压缩包内容确认文件范围。保留其他自定义模板。
|
||||
|
||||
从 `framed` 切换到 `shared` 模式时，尤其需要清理旧主题文件，否则残留的覆盖模板可能继续使用原有布局。
|
||||
先备份或移除上一主题安装的文件，选择新的邮件主题依照上述安装步骤重新操作即可。
|
||||
|
||||
### 确认生效
|
||||
|
||||
使用测试账户触发密码重置等邮件通知，检查邮件样式和链接。管理后台的测试邮件按钮不使用自定义邮件模板。
|
||||
使用测试账户触发密码重置等邮件通知，检查邮件样式和链接。管理后台的测试邮件按钮不使用自定义邮件模板，因此无法确认邮件模板是否生效。
|
||||
|
||||
## 预览
|
||||
|
||||
预览支持切换主题、邮件类型和语言，查看渲染结果或 HTML 源码，切换桌面与移动端视口，以及查看示例数据面板。v28.0.0 快照包含 11 种邮件类型和 28 种语言。
|
||||
通过仓库中提供的预览工具，可以在部署前预览邮件不同主题，不同模板类型和语言的渲染效果
|
||||
|
||||
### 静态预览
|
||||
|
||||
在源码仓库中生成预览数据：
|
||||
首先需要在源码仓库中生成预览数据：
|
||||
|
||||
```bash
|
||||
cd tools
|
||||
@@ -95,16 +98,20 @@ go run . preview all
|
||||
cd ..
|
||||
```
|
||||
|
||||
在浏览器中打开 [preview/index.html](../preview/index.html)。语言数据按需加载，支持 `file://`，无需启动服务器。当前打包脚本生成的发行包包含这些数据；历史发行包保留其原有预览内容。
|
||||
在浏览器中打开 [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）刷新页面。
|
||||
打开 [http://127.0.0.1:3456](http://127.0.0.1:3456)。Go 服务器监听主题文件、共享框架、锁文件与缓存、预览测试数据的变化。一旦监听到文件更改，服务器会将邮件模板重新构建后通过发送事件（SSE）刷新页面，以实现实时热重载。
|
||||
|
||||
### 控制和快捷键
|
||||
|
||||
| 控件 | 选项或快捷键 |
|
||||
|---|---|
|
||||
@@ -113,49 +120,64 @@ go run . dev
|
||||
| 视口 | **Desktop**（1386 × 780）、**Mobile**（390 × 780）；快捷键 `d` / `m` |
|
||||
| 信息面板 | `p` 展开或收起面板 |
|
||||
|
||||
预览使用示例数据渲染模板。浏览器与邮件客户端对 CSS 的支持不同，部署前还需在目标邮件客户端中检查效果。
|
||||
> [!WARNING]
|
||||
> 预览使用示例数据渲染模板。浏览器与邮件客户端对 CSS 的支持不同，部署前还需在目标邮件客户端中检查效果。
|
||||
|
||||
## 兼容性
|
||||
|
||||
<!-- 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 -->
|
||||
<!-- TRACKER:UPSTREAM -->
|
||||
- **上游 Gitea 28.1.0：** [PENDING]
|
||||
<!-- /TRACKER:UPSTREAM -->
|
||||
|
||||
当前源码架构面向 Gitea 28 及更高版本，兼容性按锁定版本验证。新的上游版本在完成评审前保持待验证状态。早期 Gitea 版本请使用[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)推荐的发行包；其中也记录了 v1.27.2 推送通知修复不完整的问题。
|
||||
## 项目目录结构
|
||||
|
||||
生成的模板使用 Gitea 内置函数和官方翻译键，缺少的翻译回退为英文。锁定的 v28.0.0 语言文件存在已知的波兰语邀请文案格式缺陷，预览会报告 `[UPSTREAM-WARN]` 并保留官方输出。详见[已知限制](../COMPATIBILITY.md#snapshot-driven-source-status)。
|
||||
项目按共享框架、主题样式和构建工具组织。源码与文档纳入版本控制，下载的官方文件和生成的模板、预览数据不纳入版本控制。
|
||||
|
||||
## 目录结构
|
||||
### 版本控制中
|
||||
|
||||
```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/ # 生成的安装模板，不纳入版本控制
|
||||
.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
|
||||
```
|
||||
|
||||
官方模板定义通知数据、条件、主题行和 URL。共享框架将其组织为页头、操作按钮、备用链接和页脚，主题定义配色、字体与间距。`framed` 和 `shared` 模式的说明见[主题开发指南](CONTRIBUTING.zh-CN.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` 准备缺失的官方文件缓存；后续使用前会校验缓存。
|
||||
|
||||
### 模板类型
|
||||
|
||||
邮件类型从锁定的快照中发现。v28.0.0 的邮件入口如下：
|
||||
当前 Gitea 包含以下 11 种邮件模板 [1](#注释)：
|
||||
|
||||
| 文件 | 通知类型 |
|
||||
|---|---|
|
||||
@@ -175,15 +197,13 @@ build/themes/ # 生成的安装模板，不纳入版本控制
|
||||
|
||||
欢迎改进主题、工具、文档和翻译。[贡献指南](CONTRIBUTING.zh-CN.md)介绍了本地环境准备、设计规范、检查要求和发布流程。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [English README](../README.md)
|
||||
- [简体中文贡献指南](CONTRIBUTING.zh-CN.md) · [English contributor guide](../CONTRIBUTING.md)
|
||||
- [兼容性与模板参考](../COMPATIBILITY.md)
|
||||
- [画廊截图指南](images/README.md)
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目采用 [MIT 许可证](../LICENSE)。生成的发行包保留 Gitea 许可证和快照来源信息，详见[第三方声明](../THIRD_PARTY_NOTICES.md)。
|
||||
|
||||
---
|
||||
### 注释
|
||||
|
||||
[1](#注释)：[Mail templates | Gitea Documentation](https://docs.gitea.com/administration/mail-templates/)
|
||||
|
||||
本项目与 Gitea 官方无隶属关系。
|
||||
@@ -17,23 +17,6 @@ Use the same settings for every theme so images remain comparable:
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Run `npm test` without `--update-gallery` to perform the checks and capture images without changing the committed gallery.
|
||||
|
||||
## Manual 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.
|
||||
|
||||
Reference in new issue
Block a user