Contributing to Gitea Mail Templates

Thanks for your interest in contributing! This project aims to provide a diverse, well-maintained collection of email templates for the Gitea ecosystem.

Ways to Contribute

Adding a New Style

Scaffold the new style: cd tools && go run . create <your-style-name> — this creates the directory structure with placeholder .tmpl files for all 11 email types
Edit each .tmpl file in themes/<your-style-name>/ with your unique visual design
Regenerate the preview: cd tools && go run . preview all — the build script auto-discovers all theme directories under themes/ and generates the theme selector dynamically
Submit a PR with screenshots of rendered emails (≤ 50 KiB each, 10–20 KiB recommended)

Style Guidelines

Each style must include all 11 template types listed in the README
Use only Gitea's built-in template functions — check the Gitea source for reference
Translation keys must come from Gitea's official locale files (mail.* namespace)
Never reference .DisplayName in templates where the data context lacks it (collaborator, transfer, release, workflow_run, assigned, default)
Design for 600px max-width email clients
Test against major email clients (Gmail, Outlook, Apple Mail) when possible

Bug Reports

If a template doesn't render correctly:

Check that all referenced Go template variables exist — compare against the Gitea source mail templates
Verify translation keys match Gitea's locale files
Confirm .DisplayName isn't used in templates that lack it
Regenerate the preview: cd tools && go run . preview all
Open an issue with: the style name, which email type, and the error or unexpected output

Documentation Improvements

Documentation updates, preview screenshots, installation guides, and translations are always welcome.

Development Setup

Go 1.21+ for template rendering and the CLI tool
Node.js 18+ (optional) for the live-reload dev server with Juice CSS inlining

Previewing Locally (Static)

Run cd tools && go run . preview all to generate rendered data
Open preview/index.html directly in a browser — no server needed
Use the theme switcher, template selector, and client mode toggles

Warning

Static Gmail/Outlook simulation is approximate. Use dev mode for relatively accurate rendering.

Dev Server (Live Reload + CSS Inlining + Client Simulation)

cd tools && go run . dev
# → http://localhost:3456

Watches themes/**/*.tmpl — auto-rebuilds on save
Runs Juice to inline <style> into style="" attributes
Generates three rendered.js variants: modern (Juice only), Gmail (Juice + CSS strip), Outlook (Juice + aggressive CSS strip)
Pushes live reload to browser via WebSocket
Terminal output: themes/aurora/mail/repo/release.tmpl edited → [rebuild] done in 480ms

Note

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

Integration Testing

Deploy the templates to a Gitea instance and verify with real transactional emails. The admin test email (Site Administration > Configuration > Mailer > Send Test Email) does not use custom mail templates — it follows a built-in code path.

The most reliable method is to trigger a real notification. For example, the password reset flow:

Log out and click "Forgot password" on the login page
Enter your account email and submit
Check the password reset email — it will render with your custom mail templates

Commit Conventions

Any readable commit message in semantic format is welcome. Such as:

style(horizon|terminal|ember|bloom|heritage|neon|mono|terra|ink|aurora): — template changes
preview(*): — preview tooling changes
tools(*): — Go build script changes
docs(*): — documentation and translations
fix(*): — bug fixes
project(*): — README, LICENSE, AGENTS.md, meta

Translations

License

By contributing, you agree that your contributions will be licensed under the MIT License.

4.4 KiB Raw Blame History Unescape Escape