GiteaMailTemplates/README.md

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

---

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

# 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

Send a test email from the Gitea admin panel: Site Administration > Configuration > Mailer > Send Test Email

---

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

Warning

Gmail/Outlook simulation in static mode is approximate. Use dev mode for relatively accurate CSS inlining.

Dev Server (Live Reload + Juice CSS Inlining)

Start a development server that watches for .tmpl changes, auto-rebuilds, inlines CSS for email client compatibility, and pushes live updates to the browser:

cd tools && go run . dev      # requires Node.js
open http://localhost:3456

Capability	Static	Dev
Go template rendering	✅	✅
Theme/template switching	✅	✅
Juice CSS inlining	—	✅
Gmail/Outlook CSS stripping	—	✅
Live reload on save	—	✅
Node.js required	—	✅

Note

Dev simulation cannot 100% reproduce every email client — for reference only; always verify against real clients.

Features

• Theme switcher — browse all 10 visual styles
• Template switcher — all 11 email types
• Client simulation — Modern, Gmail, Outlook, Raw Source (CSS stripping in dev mode)
• Viewport toggle — Desktop 1386×780 / Mobile 390×780
• Parameter panel — mock data per email type
• Keyboard shortcuts — ←→ tab between Theme/Template/Client, ↑↓ 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/                 # 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
• Simplified Chinese
• Traditional Chinese
• Russian
• Japanese
• Korean

---

Contributing

See CONTRIBUTING.md for guidelines. Multi-language versions 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.}