98 lines
6.1 KiB
Markdown
98 lines
6.1 KiB
Markdown
# 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]. <!-- TRACKER:UPSTREAM -->
|
||
- 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)
|