chore(init): scaffold Gitea mail templates — 110 templates, 10 visual styles, drop-in deployment

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 18:10:22 +08:00
commit a2742887e8
@@ -0,0 +1,191 @@
+# 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](docs/images/horizon.png) | **Horizon** | Enterprise / Corporate | Blue accent, slate typography, centered cards |
+| ![Terminal](docs/images/terminal.png) | **Terminal** | Developers / Tech | Dark mode, monospace, green CLI accents |
+| ![Ember](docs/images/ember.png) | **Ember** | Community / Open Source | Warm amber, rounded, humanist, inclusive |
+| ![Bloom](docs/images/bloom.png) | **Bloom** | Creative / Startup | Frosted glass, soft blue light, iridescent accents |
+| ![Heritage](docs/images/heritage.png) | **Heritage** | Education / Research | Navy and gold, serif, classic, authoritative |
+| ![Neon](docs/images/neon.png) | **Neon** | Gaming / Web3 / Creative Tech | Cyberpunk neon glow, hot pink & cyan, synthwave energy |
+| ![Mono](docs/images/mono.png) | **Mono** | Design Studios / Editorial | Swiss brutalist, black & white, red accent, zero radius |
+| ![Terra](docs/images/terra.png) | **Terra** | Sustainability / Wellness | Warm earth tones, organic textures, humanist serif |
+| ![Ink](docs/images/ink.png) | **Ink** | Publishing / News / Literature | Editorial print, navy & gold, newspaper layout, drop caps |
+| ![Aurora](docs/images/aurora.png) | **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
+go run ./tools/build-preview.go
+```
+
+Then open `preview/index.html` directly in a browser. No server required.
+
+> `preview/rendered.js` is generated and git-ignored. Re-run the command after modifying templates.
+
+### Features
+
+- Theme switcher — toggle between all 5 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/               # 5 visual styles, 11 .tmpl files each
+│   ├── horizon/          # Enterprise / Corporate
+│   ├── terminal/         # Developers / Tech
+│   ├── ember/            # Community / Open Source
+│   ├── bloom/            # Creative / Startup
+│   └── heritage/         # Education / Research
+├── preview/              # Live preview SPA
+│   ├── index.html        # Style/template/client/viewport switcher
+│   └── rendered.js       # Pre-rendered templates (generated by tools/)
+├── tools/                # Build tooling
+│   ├── build-preview.go  # Go build script — renders all templates
+│   └── 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>