222 lines
9.0 KiB
Markdown
222 lines
9.0 KiB
Markdown
# Gitea Mail Templates
|
||
<!-- DOC-TAGS: {"TRACKER":["BADGE","LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
|
||
|
||
Polished, drop-in email template themes for self-hosted [Gitea](https://about.gitea.com).
|
||
|
||
<!-- TRACKER:BADGE -->
|
||
[](COMPATIBILITY.md)
|
||
<!-- /TRACKER:BADGE -->
|
||
|
||
<!-- RELEASE:HEADER -->
|
||
> Latest Release: [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
|
||
<!-- /RELEASE:HEADER -->
|
||
|
||
---
|
||
|
||
## Philosophy
|
||
|
||
Most self-hosted Gitea instances use the default plain email templates. This project provides **ready-to-deploy, visually polished alternatives** — each designed for a specific community or audience, so you can pick the one that feels right for your users.
|
||
|
||
The templates on `main` can replace Gitea's built-in mail templates without patches, plugins, or forks. Check the [compatibility matrix](COMPATIBILITY.md) before using a published archive; older releases may have version-specific limitations.
|
||
|
||
---
|
||
|
||
## Style Gallery
|
||
|
||
| Preview | Style | Audience | Character |
|
||
|---|---|---|---|
|
||
|  | **Horizon** | Enterprise / Corporate | Blue accent, slate typography, centered cards |
|
||
|  | **Terminal** | Developers / Tech | Dark mode, monospace, green CLI accents |
|
||
|  | **Ember** | Community / Open Source | Warm amber, rounded, humanist, inclusive |
|
||
|  | **Bloom** | Creative / Startup | Frosted glass, soft blue light, iridescent accents |
|
||
|  | **Heritage** | Education / Research | Navy and gold, serif, classic, authoritative |
|
||
|  | **Neon** | Gaming / Web3 / Creative Tech | Cyberpunk neon glow, hot pink & cyan, synthwave energy |
|
||
|  | **Mono** | Design Studios / Editorial | Swiss brutalist, black & white, red accent, zero radius |
|
||
|  | **Terra** | Sustainability / Wellness | Warm earth tones, organic textures, humanist serif |
|
||
|  | **Ink** | Publishing / News / Literature | Editorial print, navy & gold, newspaper layout, drop caps |
|
||
|  | **Aurora** | Premium SaaS / Mindfulness | Ethereal light gradients, deep purple & teal, atmospheric glow |
|
||
|
||
The gallery shows the themes currently included in this repository; new themes can be added as separate directories under `themes/`.
|
||
|
||
> Images are screenshots from the [local preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions.
|
||
|
||
[**Local preview gallery**](preview/index.html) — generate the preview data as described below, then open it in a browser for an interactive style switcher with desktop/mobile viewports and view mode (Modern, Source).
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### Quick Start
|
||
|
||
Choose a style, then copy the `mail/` directory into your Gitea custom templates path:
|
||
|
||
```bash
|
||
# Locate your Gitea custom directory
|
||
# (set by GITEA_CUSTOM; defaults shown below)
|
||
|
||
# Copy templates (example: Horizon style)
|
||
cp -r themes/horizon/mail/* /var/lib/gitea/custom/templates/mail/
|
||
|
||
# Restart Gitea
|
||
systemctl restart gitea
|
||
```
|
||
|
||
### Custom Directory Location
|
||
|
||
| Platform | Default Path |
|
||
|---|---|
|
||
| Linux (binary) | `/var/lib/gitea/custom` |
|
||
| Linux (Docker) | `/data/gitea` |
|
||
| Windows | `C:\gitea\custom` |
|
||
|
||
### Switching Styles
|
||
|
||
Overwrite the files with a different style. All templates share the exact same variable structure — no configuration changes needed.
|
||
|
||
```bash
|
||
cp -r themes/terminal/mail/* /var/lib/gitea/custom/templates/mail/
|
||
systemctl restart gitea
|
||
```
|
||
|
||
### Confirming It Works
|
||
|
||
The admin test email does not use custom mail templates. To verify your templates
|
||
are active, trigger a real email notification. The quickest way is the password
|
||
reset flow: log out, click **"Forgot password"** on the login page, and check the
|
||
reset email — it will render with your custom styles.
|
||
|
||
---
|
||
|
||
## Preview
|
||
|
||
Two modes are available — a static preview that needs no server after generation, and a live-reload dev server for design work. A source clone must generate preview data first. Existing v28.0.0 and earlier archives do not contain the preview or gallery screenshots; the updated packaging workflow includes both for future builds.
|
||
|
||
### Static Preview
|
||
|
||
From a source clone, generate the preview data once, then open the HTML file in a browser:
|
||
|
||
```bash
|
||
cd tools
|
||
go run . preview all
|
||
cd ..
|
||
# Open preview/index.html in a browser; no server is needed.
|
||
```
|
||
|
||
### Dev Server (Live Reload)
|
||
|
||
Start a pure Go development server that watches for `.tmpl` changes, auto-rebuilds, and pushes live updates to the browser via SSE:
|
||
|
||
```bash
|
||
cd tools
|
||
go run . dev
|
||
# Open http://localhost:3456 in a browser.
|
||
```
|
||
|
||
| Capability | Static | Dev |
|
||
|-----------|--------|-----|
|
||
| Go template rendering | [YES] | [YES] |
|
||
| Theme/template switching | [YES] | [YES] |
|
||
| Live reload on save | [NO] | [YES] |
|
||
|
||
### Features
|
||
|
||
- Theme switcher — browse all available visual styles
|
||
- Template switcher — all 11 email types
|
||
- View mode — Modern (rendered preview), Source (raw HTML)
|
||
- Viewport toggle — Desktop 1386×780 / Mobile 390×780
|
||
- Parameter panel — mock data per email type
|
||
- Keyboard shortcuts — `←→` tab between Theme/Template/View, `↑↓` select within, `d`/`m` viewport
|
||
|
||
---
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
gitea-mail-templates/
|
||
├── themes/ # One directory per visual style, 11 .tmpl files each
|
||
│ ├── ... # Custom styles are added here as separate directories
|
||
├── preview/ # Live preview SPA
|
||
│ ├── index.html # Style/template/client/viewport switcher
|
||
│ └── rendered.js # Generated by tools/; ignored in source clones
|
||
├── tools/ # Modular CLI tooling
|
||
│ ├── tools.go # Main entry point
|
||
│ ├── cli/ # CLI subcommands (list, create, delete, preview)
|
||
│ ├── config/ # Config types and templates_config.json loading
|
||
│ ├── data/ # templates_config.json — single source of truth
|
||
│ ├── preview/ # Template rendering engine
|
||
│ └── go.mod
|
||
├── docs/ # Bilingual documentation (English + Simplified Chinese)
|
||
├── AGENTS.md # AI agent guidance
|
||
├── CONTRIBUTING.md
|
||
├── LICENSE
|
||
├── README.md
|
||
└── .gitignore
|
||
```
|
||
|
||
### Template Types
|
||
|
||
| File | Email Trigger |
|
||
|---|---|
|
||
| `mail/user/auth/activate.tmpl` | Account activation |
|
||
| `mail/user/auth/activate_email.tmpl` | Email address verification |
|
||
| `mail/user/auth/register_notify.tmpl` | New registration notification |
|
||
| `mail/user/auth/reset_passwd.tmpl` | Password reset |
|
||
| `mail/org/team_invite.tmpl` | Team invitation |
|
||
| `mail/repo/collaborator.tmpl` | Repository collaborator added |
|
||
| `mail/repo/transfer.tmpl` | Repository ownership transfer |
|
||
| `mail/repo/release.tmpl` | New release published |
|
||
| `mail/repo/actions/workflow_run.tmpl` | Actions workflow run |
|
||
| `mail/repo/issue/assigned.tmpl` | Issue / Pull Request assigned |
|
||
| `mail/repo/issue/default.tmpl` | Issue / Pull Request updates |
|
||
|
||
---
|
||
|
||
## Compatibility
|
||
|
||
<!-- TRACKER:LATEST-TESTED -->
|
||
- **Latest tested:** Gitea 28.0.0
|
||
<!-- /TRACKER:LATEST-TESTED -->
|
||
<!-- RELEASE:SUMMARY -->
|
||
- **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
|
||
<!-- /RELEASE:SUMMARY -->
|
||
- For other Gitea versions, check the [per-version compatibility matrix](COMPATIBILITY.md#compatibility-matrix) before choosing an archive; [PENDING] rows have no verified recommendation. The matching v1.27.2 tag has a known push-notification defect.
|
||
<!-- TRACKER:UPSTREAM -->
|
||
- **Upstream Gitea 28.1.0:** [PENDING]
|
||
<!-- /TRACKER:UPSTREAM -->
|
||
- The current source uses Gitea's official template data paths — see [COMPATIBILITY.md](COMPATIBILITY.md) for release-specific limitations
|
||
- Uses only built-in Gitea template functions and official translation keys
|
||
- No custom template functions or locale patches required
|
||
|
||
---
|
||
|
||
## Design Principles
|
||
|
||
1. **Responsive** — Max-width 600px cards; works in all email clients
|
||
2. **Accessible** — 4.5:1 contrast ratios; semantic HTML
|
||
3. **Graceful degradation** — Fallback link visible when buttons fail to render
|
||
4. **Logo support** — References `{{AppUrl}}assets/img/favicon.png` by default
|
||
5. **Locale-aware** — Notification text uses Gitea's `{{.locale.Tr}}` system; some decorative labels remain theme-specific English text
|
||
|
||
---
|
||
|
||
## Documentation
|
||
|
||
- [English](README.md)
|
||
- [简体中文](docs/README.zh-CN.md)
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. A Simplified Chinese translation is available in [docs/](docs/).
|
||
|
||
## License
|
||
|
||
MIT — see [LICENSE](LICENSE). Free to use, modify, and distribute in any Gitea deployment.
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<sub>Not affiliated with the Gitea project. Gitea is a community-managed lightweight code hosting solution written in Go.</sub>
|
||
</p>
|