1 Fork 0

Files

T

KenanZhuandClaude Opus 4.8 0bf982ffb9 refactor(tools): modularize CLI with urfave/cli/v2, externalise template metadata

- Split monolithic build-preview.go into modular packages:
  tools.go (entry), cli/ (list/create/delete/preview commands),
  config/ (JSON loading), preview/ (rendering engine, funcs, locale)
- Extract all template metadata into data/templates_config.json
  as single source of truth — no hardcoded template data in Go
- Replace hand-rolled CLI parsing with github.com/urfave/cli/v2
- Add sensible defaults for --folder (../themes) and --config
  (./data/templates_config.json) — most commands now run bare
- Add type-coercing gt/lt/ge/le template funcs for JSON float64
- Fix AppUrl to gitea.com matching official template convention
- rendered.js now exports __REGISTRY__ and __PARAMS__ alongside
  __RENDERED__ — preview/index.html reads all from single source
- Cross-validate all 11 template data contexts against official
  Gitea source (services/mailer/*.go + templates/mail/*.tmpl)
- Update all docs (README, AGENTS, CONTRIBUTING, 5 languages)
  to reflect new CLI workflow with create scaffolding command

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-04 12:26:44 +08:00

3.5 KiB

Raw Blame History

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

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

No build tools or dependencies are needed — these are raw Go HTML templates.

Previewing Locally

Open preview/index.html directly in a browser — no server needed
Use the theme switcher, template selector, and client mode toggles to review designs
Toggle between Modern, Gmail, Outlook, and Raw source modes to verify degradation

Regenerating Previews

cd tools && go run . preview all

This renders all templates (themes auto-discovered from the themes/ directory) using Go's native html/template package and writes the output to preview/rendered.js. The --folder and --config flags default to ../themes and ./data/templates_config.json respectively — override them only when using a custom layout.

Integration Testing

Deploy the templates to a Gitea instance and use the admin test email feature: Site Administration > Configuration > Mailer > Send Test Email

Commit Conventions

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.

3.5 KiB Raw Blame History