KenanZhuandClaude Opus 4.8
0bf982ffb9
- Split monolithic build-preview.go into modular packages: tools.go (entry), cli/ (list/create/delete/preview commands), config/ (JSON loading), preview/ (rendering engine, funcs, locale) - Extract all template metadata into data/templates_config.json as single source of truth — no hardcoded template data in Go - Replace hand-rolled CLI parsing with github.com/urfave/cli/v2 - Add sensible defaults for --folder (../themes) and --config (./data/templates_config.json) — most commands now run bare - Add type-coercing gt/lt/ge/le template funcs for JSON float64 - Fix AppUrl to gitea.com matching official template convention - rendered.js now exports __REGISTRY__ and __PARAMS__ alongside __RENDERED__ — preview/index.html reads all from single source - Cross-validate all 11 template data contexts against official Gitea source (services/mailer/*.go + templates/mail/*.tmpl) - Update all docs (README, AGENTS, CONTRIBUTING, 5 languages) to reflect new CLI workflow with create scaffolding command Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
192 lines
7.4 KiB
Markdown
192 lines
7.4 KiB
Markdown
# Gitea Mail Templates
|
|
|
|
A curated collection of professionally designed, audience-driven email templates for self-hosted [Gitea](https://about.gitea.com) instances.
|
|
|
|
> **110 template files — 10 visual styles, 11 email types each**
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
Every template is a drop-in replacement. All Go template variables, translation keys, and Gitea data contexts are fully compatible. **No patches, no plugins, no forks required.**
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|
|
> Images are 600px screenshots from the [live preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions.
|
|
|
|
[**Live preview gallery**](preview/index.html) — open in a browser for an interactive style switcher with desktop/mobile viewports and email client simulation (Modern, Gmail, Outlook, Raw 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
|
|
|
|
Send a test email from the Gitea admin panel:
|
|
**Site Administration > Configuration > Mailer > Send Test Email**
|
|
|
|
---
|
|
|
|
## Preview
|
|
|
|
A live preview tool is included to browse all styles and email types without deploying to a Gitea instance.
|
|
|
|
### Quick Start
|
|
|
|
First, generate the preview data (requires Go):
|
|
|
|
```bash
|
|
cd tools && go run . preview all
|
|
```
|
|
|
|
Then open `preview/index.html` directly in a browser. No server required.
|
|
|
|
> `preview/rendered.js` is generated and git-ignored. Re-run `cd tools && go run . preview all` after modifying templates. Use `cd tools && go run .` to see all commands (list, create, delete, preview). Most flags have sensible defaults — just `go run . create <name>` or `go run . preview all` works out of the box.
|
|
|
|
### Features
|
|
|
|
- Theme switcher — toggle between all 10 visual styles
|
|
- Template switcher — browse all 11 email types
|
|
- Client simulation — Modern, Gmail (no `<style>`), Outlook Desktop, Raw source
|
|
- Viewport toggle — Desktop (1386x780) / Mobile (390x780)
|
|
- Parameter panel — view template variables and mock data per email type
|
|
- Keyboard shortcuts — `←→` templates, `d` desktop, `m` mobile
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
gitea-mail-templates/
|
|
├── themes/ # 10 visual styles, 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 # Pre-rendered templates (generated by tools/)
|
|
├── 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/ # Multi-language documentation
|
|
├── 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
|
|
|
|
- **Gitea 1.21+** (all versions with Go 1.21 template support)
|
|
- 100% variable-compatible with official Gitea templates
|
|
- Uses only built-in Gitea template functions
|
|
- Uses only official Gitea 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. **i18n-ready** — All user-facing strings use Gitea's `{{.locale.Tr}}` system
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
- [English](README.md)
|
|
- [Simplified Chinese](docs/README.zh-CN.md)
|
|
- [Traditional Chinese](docs/README.zh-TW.md)
|
|
- [Russian](docs/README.ru.md)
|
|
- [Japanese](docs/README.ja.md)
|
|
- [Korean](docs/README.ko.md)
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Multi-language versions 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>
|