chore: streamline compatibility tracking and documentation
This commit is contained in:
KenanZhu committed
1 parent
92d2ba9889
commit
23f0456622
16 files changed
+476
-259
No files matched your search
@@ -34,14 +34,13 @@
|
||||
|
||||
## 开发环境
|
||||
|
||||
- **Go 1.21+** 用于模板渲染和 CLI 工具
|
||||
- **Go 1.21+** 用于模板渲染和 CLI 工具；Go 模块需下载 `github.com/urfave/cli/v2` 及其依赖
|
||||
|
||||
### 本地预览（静态）
|
||||
|
||||
1. 先生成预览数据：`cd tools && go run . preview all`
|
||||
2. 在浏览器中打开 `preview/index.html` — 无需服务器
|
||||
|
||||
|
||||
### 开发服务器（实时重载）
|
||||
|
||||
```bash
|
||||
@@ -49,8 +48,7 @@ cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
修改 `.tmpl` 文件后自动重建并推送至浏览器。
|
||||
|
||||
修改 `.tmpl` 文件后自动重建并推送至浏览器。HTTP 服务与 SSE 实时重载使用 Go 标准库实现，CLI 本身依赖 Go 模块。
|
||||
|
||||
### 集成测试
|
||||
|
||||
@@ -75,6 +73,11 @@ cd tools && go run . dev
|
||||
- `fix:` — Bug 修复
|
||||
- `project:` — README、LICENSE、元文件
|
||||
|
||||
## 翻译
|
||||
|
||||
- [English CONTRIBUTING](../CONTRIBUTING.md)
|
||||
- 简体中文（本文）
|
||||
|
||||
## 许可协议
|
||||
|
||||
参与贡献即表示您同意将您的贡献以 MIT 许可证授权。
|
||||
+41
-13
@@ -1,8 +1,8 @@
|
||||
# Gitea 邮件模板
|
||||
|
||||
为自托管 [Gitea](https://about.gitea.com) 实例精心设计、面向不同受众的邮件模板集合。
|
||||
为自托管 [Gitea](https://about.gitea.com) 提供精心设计、可直接部署的多风格邮件模板。
|
||||
|
||||
> **发布版 v28.0.0 — 已通过 Gitea 28.0.0 兼容性检查 — 110 个模板文件、10 种视觉风格、每种 11 种邮件类型**
|
||||
> 最新发布版：[v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.0.0)
|
||||
|
||||
---
|
||||
|
||||
@@ -29,9 +29,9 @@
|
||||
|  | **Ink** | 出版/新闻/文学 | 编辑印刷、深蓝与金色、报纸排版 |
|
||||
|  | **Aurora** | 高端SaaS/正念 | 空灵光效渐变、深紫与青绿、大气光晕 |
|
||||
|
||||
> 图片为 600px 宽截图，来自[在线预览](../preview/index.html)。截图方法参见 [images/README.md](images/README.md)。
|
||||
> 图片为 600px 宽截图，来自[本地预览](../preview/index.html)。截图方法参见 [images/README.md](images/README.md)。
|
||||
|
||||
[**在线预览画廊**](../preview/index.html)
|
||||
[**本地预览画廊**](../preview/index.html) — 先按下文生成预览数据，再在浏览器中打开。
|
||||
|
||||
---
|
||||
|
||||
@@ -46,6 +46,8 @@ systemctl restart gitea
|
||||
|
||||
切换风格只需覆盖文件，无需更改配置。
|
||||
|
||||
`GITEA_CUSTOM` 决定自定义目录；常见路径为 Linux 二进制部署的 `/var/lib/gitea/custom`、Docker 的 `/data/gitea`，以及 Windows 的 `C:\gitea\custom`。
|
||||
|
||||
### 确认生效
|
||||
|
||||
管理后台的测试邮件不会使用自定义模板。要验证模板是否生效，请触发一次真实的
|
||||
@@ -56,33 +58,59 @@ systemctl restart gitea
|
||||
|
||||
## 预览
|
||||
|
||||
从源码克隆时，需先生成被忽略的 `preview/rendered.js`。现有 v28.0.0 及更早的压缩包未包含预览文件和画廊截图；更新后的打包流程会在后续构建中加入两者。
|
||||
|
||||
**静态模式：**
|
||||
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
cd tools
|
||||
go run . preview all
|
||||
cd ..
|
||||
```
|
||||
然后打开 `preview/index.html`。
|
||||
|
||||
然后在浏览器中打开 `preview/index.html`，无需启动服务器。
|
||||
|
||||
**开发服务器（实时重载）：**
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
cd tools
|
||||
go run . dev
|
||||
# 在浏览器中打开 http://localhost:3456
|
||||
```
|
||||
|
||||
| 功能 | 静态 | Dev |
|
||||
|-----------|--------|-----|
|
||||
| Go 模板渲染 | ✅ | ✅ |
|
||||
| 主题/模板切换 | ✅ | ✅ |
|
||||
| 实时重载 | — | ✅ |
|
||||
| Go 模板渲染 | [YES] | [YES] |
|
||||
| 主题/模板切换 | [YES] | [YES] |
|
||||
| 实时重载 | [NO] | [YES] |
|
||||
|
||||
预览支持主题与模板切换、Modern/Source 视图、桌面/移动端尺寸以及模板参数面板。`←→` 可切换选择框，`↑↓` 可切换选项，`d`/`m` 可切换视口。
|
||||
|
||||
---
|
||||
|
||||
## 兼容性
|
||||
|
||||
- **Gitea 28.0.0** — 使用模板发布版 v28.0.0；旧版 Gitea 请选用对应的旧版模板
|
||||
- **最新测试：** Gitea 28.0.0<!-- TRACKER:LATEST-TESTED -->
|
||||
- **最新发布版：** [v28.0.0](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.0.0) 已将全部 10 个主题的发布通知适配为 `FormatByteSize`；Gitea 1.25.0–1.27.3 请使用 [v1.27.3](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3)（详见[兼容性说明](../COMPATIBILITY.md)）
|
||||
- **最新测试：** Gitea 28.0.0 <!-- TRACKER:LATEST-TESTED -->
|
||||
- **最新发布版：** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.0.0) 已将全部 10 个主题的发布通知适配为 `FormatByteSize`；Gitea 1.25.0–1.27.3 请使用 [v1.27.3](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3)（详见[兼容性说明](../COMPATIBILITY.md)）
|
||||
- **上游 Gitea 28.1.0：** [PENDING] <!-- TRACKER:UPSTREAM -->
|
||||
- 当前源码使用 Gitea 官方模板的数据路径；各发布版的限制详见 [兼容性说明](../COMPATIBILITY.md)
|
||||
|
||||
## 模板类型
|
||||
|
||||
每种风格都提供 11 种邮件类型：账户激活、邮箱验证、注册通知、密码重置、团队邀请、仓库协作者、仓库转移、新版发布、Actions 工作流、议题/合并请求指派及议题/合并请求更新。具体文件路径参见[英文 README](../README.md#template-types)。
|
||||
|
||||
## 设计与翻译
|
||||
|
||||
模板采用适合邮件客户端的响应式布局，并提供按钮失效时可用的备用链接。通知正文使用 Gitea 的翻译系统；部分主题装饰性标签仍为英文，并非所有可见文字都已本地化。
|
||||
|
||||
## 文档与贡献
|
||||
|
||||
- [English README](../README.md)
|
||||
- [简体中文 README](README.zh-CN.md)
|
||||
- [English CONTRIBUTING](../CONTRIBUTING.md)
|
||||
- [简体中文贡献指南](CONTRIBUTING.zh-CN.md)
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT — 详见 [LICENSE](../LICENSE)。
|
||||
@@ -1,6 +1,6 @@
|
||||
# Style Preview Images
|
||||
|
||||
Place theme style screenshots of **Desktop** in PNG format here, captured from the [live preview](../preview/index.html).
|
||||
Place theme style screenshots of **Desktop** in PNG format here, captured from the [local preview](../../preview/index.html).
|
||||
|
||||
## Naming Convention
|
||||
|
||||
@@ -14,7 +14,7 @@ neon.png mono.png terra.png ink.png aurora.png
|
||||
To ensure screenshots can be displayed in the README, please follow these size requirements:
|
||||
|
||||
- **Maximum:** 50 KiB per image
|
||||
- **Recommended:** 30–40 KiB
|
||||
- **Recommended:** 10–20 KiB
|
||||
- **Format:** PNG, optimised — run through `pngquant` or `optipng` before committing
|
||||
|
||||
## How to Capture
|
||||
@@ -24,4 +24,4 @@ To ensure screenshots can be displayed in the README, please follow these size r
|
||||
3. Take a screenshot of the rendered email (600px width recommended)
|
||||
4. Save as `<style-name>.png` in this directory
|
||||
|
||||
> For static preview, run `cd tools && go run . preview all` then open `preview/index.html` directly.
|
||||
> For a source clone, run `cd tools && go run . preview all`, return to the repository root, then open `preview/index.html` directly.
|
||||
@@ -1,92 +0,0 @@
|
||||
# Spec: Remove Juice & Simplify Preview Module
|
||||
|
||||
**Date:** 2026-06-23
|
||||
**Status:** approved
|
||||
|
||||
## Goal
|
||||
|
||||
Remove multi-email-client simulation (Gmail/Outlook) from the preview module, eliminate the `juice` CSS-inlining dependency, and rewrite the dev server in pure Go with SSE-based live reload.
|
||||
|
||||
## Motivation
|
||||
|
||||
- Multi-client CSS simulation has diminishing value — modern email clients render consistently
|
||||
- `juice` + Node.js adds complexity (npm install, node_modules, separate runtime)
|
||||
- The project already uses Go for all build tooling; a Node.js dev server is an outlier
|
||||
- Simplifying to "Modern" and "Source" views covers the real use cases
|
||||
|
||||
## Changes
|
||||
|
||||
### 1. Delete `tools/server/` (entire directory)
|
||||
|
||||
Remove all Node.js artifacts:
|
||||
- `inliner.mjs` — juice CSS inlining + Gmail/Outlook CSS stripping
|
||||
- `server.mjs` — Express + WebSocket dev server
|
||||
- `package.json` / `package-lock.json`
|
||||
- `node_modules/` — all npm dependencies
|
||||
|
||||
### 2. Rewrite `tools/cli/dev.go`
|
||||
|
||||
- Remove Node.js dependency check
|
||||
- Remove `exec.Command("node", "server.mjs")` subprocess
|
||||
- Instead: create and start a pure Go HTTP server (calling into `tools/preview/server.go`)
|
||||
- Keep the same CLI interface: `go run . dev [--port <port>]`
|
||||
|
||||
### 3. New file: `tools/preview/server.go`
|
||||
|
||||
Pure Go dev server with:
|
||||
- **Static file serving** — serve `preview/` directory (index.html, rendered.js)
|
||||
- **SSE endpoint** (`GET /events`) — Server-Sent Events for browser reload notifications
|
||||
- **File watcher** — poll `themes/` every 500ms, compare mod times of `.tmpl` files
|
||||
- **On change detected** — call `preview.RenderAll()` directly (in-process, no subprocess), write `rendered.js`, broadcast SSE `reload` event
|
||||
- No external Go dependencies — uses `net/http` stdlib only
|
||||
|
||||
### 4. Modify `preview/index.html`
|
||||
|
||||
Frontend changes:
|
||||
- **Client selector** — reduce from 4 options (Modern/Gmail/Outlook/Raw Source) to 2 (Modern/Source)
|
||||
- **Remove** `renderedGmail` / `renderedOutlook` variables and all Gmail/Outlook JS logic
|
||||
- **Simplify** `getRendered()` — always returns `rendered`
|
||||
- **Simplify** `transform()` — only handles `source` mode (HTML escaping)
|
||||
- **Remove** Client Simulation indicators panel (HTML section + JS in `updatePanel()`)
|
||||
- **Remove** static-mode warning message ("Gmail / Outlook simulation is approximate...")
|
||||
- **Replace** WebSocket with SSE (`new EventSource('/events')`)
|
||||
- **SSE reload handler** — dynamically reload `rendered.js` on `reload` event, re-render iframe without losing current theme/template/viewport selection
|
||||
- **Simplify** `setDevMode()` — remove multi-client disclaimer
|
||||
|
||||
### 5. Update `AGENTS.md`
|
||||
|
||||
- Remove references to Juice, Node.js, Gmail/Outlook variants
|
||||
- Update dev server description to reflect pure Go implementation
|
||||
|
||||
## Non-Changes
|
||||
|
||||
- `tools/preview/engine.go` — template rendering engine unchanged
|
||||
- `tools/preview/funcs.go` — template functions unchanged
|
||||
- `tools/preview/locale.go` — locale data unchanged
|
||||
- `tools/config/` — config loading unchanged
|
||||
- `tools/data/templates_config.json` — unchanged
|
||||
- `tools/cli/preview.go` — preview command unchanged
|
||||
- `tools/cli/commands.go` — command registration unchanged
|
||||
- All theme `.tmpl` files — unchanged
|
||||
|
||||
## Behavior
|
||||
|
||||
### Static preview (open `preview/index.html` directly)
|
||||
- Works via `file://` protocol as before
|
||||
- Two view modes: Modern (rendered HTML in iframe) and Source (escaped HTML source)
|
||||
- No dev-mode warnings needed
|
||||
|
||||
### Dev mode (`go run . dev`)
|
||||
- `go run . dev` starts the Go HTTP server on port 3456 (configurable)
|
||||
- On startup: runs preview engine once, writes `rendered.js`
|
||||
- Serves `preview/` as static files
|
||||
- Watches `themes/` for `.tmpl` changes (500ms polling)
|
||||
- On change: re-renders affected themes, updates `rendered.js`, pushes SSE event
|
||||
- Browser auto-reloads preview content without page refresh (preserves UI state)
|
||||
|
||||
## Constraints
|
||||
|
||||
- No new Go dependencies — SSE and file polling use stdlib only
|
||||
- No Node.js requirement
|
||||
- `preview/rendered.js` format stays compatible: `window.__RENDERED__`, `window.__REGISTRY__`, `window.__PARAMS__`
|
||||
- Preview still works with `file://` protocol (no server needed for basic use)
|
||||
Reference in new issue
Block a user