Gitea Mail Templates
Polished, drop-in email template themes for self-hosted Gitea.
Latest Release: v28.0.0
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 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. See docs/images/README.md for capture instructions.
Local preview gallery — 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:
# 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.
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:
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:
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/mviewport
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
- Latest tested: Gitea 28.0.0
- Latest release: v28.0.0
- For other Gitea versions, check the per-version compatibility matrix before choosing an archive; [PENDING] rows have no verified recommendation. The matching v1.27.2 tag has a known push-notification defect.
- Upstream Gitea 28.1.0: [PENDING]
- The current source uses Gitea's official template data paths — see 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
- Responsive — Max-width 600px cards; works in all email clients
- Accessible — 4.5:1 contrast ratios; semantic HTML
- Graceful degradation — Fallback link visible when buttons fail to render
- Logo support — References
{{AppUrl}}assets/img/favicon.pngby default - Locale-aware — Notification text uses Gitea's
{{.locale.Tr}}system; some decorative labels remain theme-specific English text
Documentation
Contributing
See CONTRIBUTING.md for guidelines. A Simplified Chinese translation is available in docs/.
License
MIT — see 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.