Gitea Mail Templates

A curated collection of professionally designed, audience-driven email templates for self-hosted Gitea instances.

110 template files — 10 visual styles, 11 email types each. The main branch is verified with Gitea 1.27.3; push-notification fixes await a new release.

---

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

Images are screenshots from the live preview. See docs/images/README.md for capture instructions.

Live preview gallery — open 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 zero-dependency static preview for quick checks, and a live-reload dev server for design work.

Static Preview

Generate the preview data once (Go only), then open in a browser:

cd tools && go run . preview all
open preview/index.html        # no server 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

Capability	Static	Dev
Go template rendering	✅	✅
Theme/template switching	✅	✅
Live reload on save	—	✅

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       # 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/                 # 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

• Gitea 1.25+ — matches the refactored mail template directory structure (v1.25)
• Latest tested: Gitea 1.27.3
• Published release: v1.27.2. Its Bloom, Ember, and Heritage push notifications can fail on Gitea 1.27.1+; the fix is on main and awaits release (see COMPATIBILITY.md)
• 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

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
• 简体中文

---

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.}