GiteaMailTemplates/README.md

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/m viewport

---

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

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

---

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