GiteaMailTemplates/AGENTS.md

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

• 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 <!-- SUBJECT:CONTENT --> and closing <!-- /SUBJECT:CONTENT --> 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)