GiteaMailTemplates/AGENTS.md

AGENTS.md — Gitea Mail Templates

Project Overview

A curated collection of email template themes (10 visual styles) for self-hosted Gitea instances. Each theme contains 11 Go html/template files covering all Gitea notification email types.

Repository Layout

themes/             # Template themes (10 styles, 11 .tmpl each = 110 source files)
  aurora/           #   Ethereal / Dreamlike
  bloom/            #   Creative / Startup (glassmorphism)
  ember/            #   Community / Open Source
  heritage/         #   Education / Research
  horizon/          #   Enterprise / Corporate
  ink/              #   Editorial / Publishing
  mono/             #   Minimal / Swiss design
  neon/             #   Cyberpunk / Gaming
  terminal/         #   Developers / Tech
  terra/            #   Nature / Sustainability
tools/              # Go CLI tooling (modular; uses urfave/cli/v2)
  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 for template metadata
  preview/          #   Template rendering engine (funcs, locale, engine)
  go.mod            #   Go module (CLI dependency declared here)
preview/            # Browser-based live preview
  index.html        # SPA with style/template/client/viewport switching
  rendered.js       # Pre-rendered HTML (generated, ignored in source clones)
docs/               # Bilingual documentation (English + Simplified Chinese)

Working With Templates

Template Files

• All .tmpl files use Go html/template syntax
• Must use only Gitea 28's built-in template functions: AppUrl, DotEscape, QueryEscape, ShortSha, HTMLFormat, PathEscapeSegments, FormatByteSize
• Must use only official Gitea translation keys (mail.* namespace)
• Never reference .DisplayName in templates where the data context lacks it (collaborator, transfer, release, workflow_run, assigned, default)
• Each style must have all 11 template types

Adding a New Theme

1. Scaffold the new theme: cd tools && go run . create <name> — creates the full directory structure with placeholder .tmpl files for all 11 email types
2. Write all 11 .tmpl files with unique visual design
3. Run cd tools && go run . preview all to regenerate preview data
4. Update README.md style gallery table

Preview System

• preview/index.html loads preview/rendered.js (pre-rendered by Go) and displays in iframes
• Supports theme/template switching, view mode (Modern/Source), and viewport toggle (Desktop 1386x780 / Mobile 390x780)
• Keyboard navigation: ←→ cycles focus between Theme/Template/View selects, ↑↓ selects within the focused dropdown, d/m toggles viewport
• REGISTRY and PARAMS are auto-generated from templates_config.json — no manual syncing needed
• Static preview works via file:// after running go run . preview all in a source clone; the updated packaging workflow includes generated preview data and screenshots for future builds (v28.0.0 and older archives include neither)
• Dev server (go run . dev) — pure Go HTTP server with SSE live reload; watches themes/ for .tmpl changes, re-renders in-process, and pushes reload events to the browser

Build Tool

• tools/tools.go is the main entry point for the modular CLI
• Subcommands: list, create, delete, preview, dev
• Template metadata lives in tools/data/templates_config.json — the single source of truth
• tools/config/ handles config loading and data flattening
• tools/preview/ implements the rendering engine (template funcs, locale, engine, markSafeHTML)
• tools/cli/ implements CLI subcommands using github.com/urfave/cli/v2
• tools/preview/server.go pure Go dev server with SSE live reload and in-process template re-rendering
• Uses Go's native html/template package for template rendering

Versioning

• Release tags identify actual downloadable packages; the compatibility matrix distinguishes released tags from source-only fixes
• The current release is v28.0.0, verified against Gitea 28.0.0. Gitea 28 removes FileSize in favor of FormatByteSize, so v28.0.0 is not compatible with Gitea 1.25.0–1.27.3; use v1.27.3 for those versions. The quick-reference table in COMPATIBILITY.md lists the active release first
• Latest upstream Gitea release: 28.1.0 [PENDING].
• When a new Gitea version appears, the tracker updates pending rows, marked version lines, and the pending README badge. After verification, update the top COMPATIBILITY.md tested range and README tested text/badge; keep unreleased fixes distinct from the published release
• Tag a new release (vX.Y.Z) only when the template content itself changes. On the new Gitea host, do not assume tag pushes automatically build or upload archives; verify the Gitea workflow before relying on it
• Before tagging, add .github/release-notes/vX.Y.Z.md, run go test ./... and go run . preview all from tools/, then build and upload the archives with the reviewed notes. .github/workflows/release.yml retains the earlier GitHub Actions flow as a reference
• Keep TRACKER:VERSION-MAP and TRACKER:HISTORY above their tables, and inline TRACKER:BADGE, TRACKER:UPSTREAM, TRACKER:LATEST-TESTED, and TRACKER:LATEST-VERIFIED markers with their text. The Python tracker updates pending markers; tested/verified markers are manual-only

Commit Conventions

• style(name): — template changes for a specific theme
• preview: — preview tooling changes
• tools: — Go CLI/build tooling changes
• docs: — documentation and translations
• fix: — bug fixes
• project: — README, LICENSE, AGENTS.md, meta
• refactor: — code restructuring (e.g. modularization)
• chore: — maintenance (config updates, build scripts)

Constraints

• No JavaScript framework dependencies — preview is vanilla JS
• The CLI uses github.com/urfave/cli/v2; the preview server itself uses Go's standard HTTP library
• Templates must remain compatible with Gitea's html/template execution environment
• Preview works with file:// protocol (no server needed)