# Gitea Mail Templates Polished, drop-in email template themes for self-hosted [Gitea](https://about.gitea.com). [![Gitea](https://img.shields.io/badge/Gitea-28.1.0%20%5BPENDING%5D%20%7C%2028.0.0%20tested-yellow)](COMPATIBILITY.md) > Latest Release: [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) --- ## 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](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 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 10 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/ # 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 # 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 - **Latest tested:** Gitea 28.0.0 - **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) - For Gitea 1.25.0–1.27.3, use [v1.27.3](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3); see [COMPATIBILITY.md](COMPATIBILITY.md) for version-specific limits. - **Upstream Gitea 28.1.0:** [PENDING] - 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. ---

Not affiliated with the Gitea project. Gitea is a community-managed lightweight code hosting solution written in Go.