# AGENTS.md — Gitea Mail Templates ## Project Overview A growing collection of email template themes for self-hosted Gitea instances. Each theme contains 11 Go `html/template` files covering all supported Gitea notification email types. ## Repository Layout ``` themes/ # One directory per theme, with 11 .tmpl files each 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 .../ # Additional themes can be added 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 ` — 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 - Current template release: **v28.0.0**. - v28.0.0 was verified against Gitea 28.0.0. Gitea 28 replaces the mail-template `FileSize` function with `FormatByteSize`; earlier template releases can fail on Gitea 28, and v28.0.0 is not a drop-in replacement for earlier mail contexts. Choose an archive from the per-version matrix in `COMPATIBILITY.md`; v1.27.2 is a known partial fix for push notifications - Latest upstream Gitea release: 28.1.0 [PENDING]. - When a new Gitea version appears, the tracker adds pending compatibility and history rows and updates marked version lines and the pending README badge. After verification, update that version's matrix row 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/`. The release workflow packages the tag, publishes the reviewed notes, and then updates `RELEASE` blocks on `main` when the host supports those Actions and write permissions; otherwise build/upload and update the labels manually - Participating Markdown documents declare their blocks in a `DOC-TAGS` JSON comment. Each block uses a paired opening `` and closing `` comment; its body is the managed text. `TRACKER` handles upstream-pending content, `RELEASE` handles published-template labels, and `TRACKER:LATEST-TESTED` / `TRACKER:LATEST-VERIFIED` are manual-only. Within a document, the first block for a subject/content pair wins ## 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)