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

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

cd tools && go run . preview all

Then open preview/index.html directly in a browser. No server required.

preview/rendered.js is generated and git-ignored. Re-run cd tools && go run . preview all after modifying templates. Use cd tools && go run . to see all commands (list, create, delete, preview). Most flags have sensible defaults — just go run . create <name> or go run . preview all works out of the box.

Features

• Theme switcher — toggle between all 10 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/               # 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.}