KenanZhu
d8a714b2b5
preview/index.html: - Fix scrollbar CSS: scoped webkit pseudo-elements + standards-track fallback, removed deprecated overflow:overlay - Keyboard navigation: arrows cycle focus between Theme/Template/Client selects, up/down select within focused dropdown, d/m toggle viewport - Dev/static mode detection: delayed static warning only when WebSocket absent, WebSocket errors only on disconnect (not on initial fail) - iframe sandbox: removed static sandbox attr, applied dynamically only in dev mode (file: protocol rejects sandboxed srcdoc) - Loading fix: removed double-toggle between init and render(); added 5s safety timeout - Transform clean: returns HTML as-is; CSS stripping moved to server-side - Dev disclaimer: blue info banner shown on WebSocket connect tools/server/inliner.mjs: - Added stripGmail() / stripOutlook() — server-side CSS property stripping for email client simulation tools/server/server.mjs: - Fixed WebSocket upgrade: use app.listen() instead of createServer(app).listen() - Juice post-processing now generates three rendered.js variants (modern/gmail/outlook) - Initial startup runs juice-only pass (avoids duplicate Go compilation) docs/ (all 6 languages — en, zh-CN, zh-TW, ja, ko, ru): - Image size limits: max 50KiB, recommended 10-20KiB - Dev disclaimer: simulation cannot 100% reproduce every client - Changed 'accurate' to 'relatively accurate' across all static-mode warnings - Converted all plain blockquotes to GitHub admonitions ([!WARNING] / [!NOTE])
83 lines
4.6 KiB
Markdown
83 lines
4.6 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, zero dependencies)
|
|
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 (stdlib only, zero dependencies)
|
|
preview/ # Browser-based live preview
|
|
index.html # SPA with style/template/client/viewport switching
|
|
rendered.js # Pre-rendered HTML (generated, committed for clone-and-preview)
|
|
docs/ # Multi-language documentation
|
|
```
|
|
|
|
## Working With Templates
|
|
|
|
### Template Files
|
|
- All `.tmpl` files use Go `html/template` syntax
|
|
- Must use only Gitea's built-in template functions: `AppUrl`, `DotEscape`, `QueryEscape`, `ShortSha`, `HTMLFormat`, `PathEscapeSegments`, `FileSize`
|
|
- 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, client simulation (Modern/Gmail/Outlook/Raw), and viewport toggle (Desktop 1386x780 / Mobile 390x780)
|
|
- Keyboard navigation: `←→` cycles focus between Theme/Template/Client 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 (open `index.html` directly) — all client modes show the same HTML; simulation warning is displayed
|
|
- Dev server (`go run . dev`) — applies Juice CSS inlining server-side, generates three `rendered.js` variants (modern/gmail/outlook) with client-specific CSS stripping; includes live reload via WebSocket
|
|
- Dev mode shows an info notice: simulation cannot 100% reproduce every email client — always verify against real clients
|
|
|
|
### 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/server/` Node.js dev server with Juice CSS inlining and live reload (Express + WebSocket + fs.watch)
|
|
- Uses Go's native `html/template` package for template rendering
|
|
|
|
## 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
|
|
- No external Go dependencies — build uses stdlib only
|
|
- Templates must remain compatible with Gitea's `html/template` execution environment
|
|
- Preview works with `file://` protocol (no server needed)
|