1 Fork 0

Files

T

KenanZhu d8a714b2b5 feat(preview): cross-browser scrollbar, keyboard nav, dev-mode client simulation, docs overhaul

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

2026-06-04 16:01:42 +08:00

4.6 KiB

Raw Blame History

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

Scaffold the new theme: cd tools && go run . create <name> — creates the full directory structure with placeholder .tmpl files for all 11 email types
Write all 11 .tmpl files with unique visual design
Run cd tools && go run . preview all to regenerate preview data
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)

4.6 KiB Raw Blame History