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

3.9 KiB

Raw Blame History

Contributing to Gitea Mail Templates

Thanks for your interest in contributing! This project aims to provide a diverse, well-maintained collection of email templates for the Gitea ecosystem.

Ways to Contribute

Adding a New Style

Scaffold the new style: cd tools && go run . create <your-style-name> — this creates the directory structure with placeholder .tmpl files for all 11 email types
Edit each .tmpl file in themes/<your-style-name>/ with your unique visual design
Regenerate the preview: cd tools && go run . preview all — the build script auto-discovers all theme directories under themes/ and generates the theme selector dynamically
Submit a PR with screenshots of rendered emails (≤ 50 KiB each, 10–20 KiB recommended)

Style Guidelines

Each style must include all 11 template types listed in the README
Use only Gitea's built-in template functions — check the Gitea source for reference
Translation keys must come from Gitea's official locale files (mail.* namespace)
Never reference .DisplayName in templates where the data context lacks it (collaborator, transfer, release, workflow_run, assigned, default)
Design for 600px max-width email clients
Test against major email clients (Gmail, Outlook, Apple Mail) when possible

Bug Reports

If a template doesn't render correctly:

Check that all referenced Go template variables exist — compare against the Gitea source mail templates
Verify translation keys match Gitea's locale files
Confirm .DisplayName isn't used in templates that lack it
Regenerate the preview: cd tools && go run . preview all
Open an issue with: the style name, which email type, and the error or unexpected output

Documentation Improvements

Documentation updates, preview screenshots, installation guides, and translations are always welcome.

Development Setup

Go 1.21+ for template rendering and the CLI tool
Node.js 18+ (optional) for the live-reload dev server with Juice CSS inlining

Previewing Locally (Static)

Run cd tools && go run . preview all to generate rendered data
Open preview/index.html directly in a browser — no server needed
Use the theme switcher, template selector, and client mode toggles

Warning

Static Gmail/Outlook simulation is approximate. Use dev mode for relatively accurate rendering.

Dev Server (Live Reload + CSS Inlining + Client Simulation)

cd tools && go run . dev
# → http://localhost:3456

Watches themes/**/*.tmpl — auto-rebuilds on save
Runs Juice to inline <style> into style="" attributes
Generates three rendered.js variants: modern (Juice only), Gmail (Juice + CSS strip), Outlook (Juice + aggressive CSS strip)
Pushes live reload to browser via WebSocket
Terminal output: themes/aurora/mail/repo/release.tmpl edited → [rebuild] done in 480ms

Note

Dev simulation cannot 100% reproduce every email client — for reference only; always verify against real clients.

Integration Testing

Deploy the templates to a Gitea instance and use the admin test email feature: Site Administration > Configuration > Mailer > Send Test Email

Commit Conventions

style(horizon|terminal|ember|bloom|heritage|neon|mono|terra|ink|aurora): — template changes
preview: — preview tooling changes
tools: — Go build script changes
docs: — documentation and translations
fix: — bug fixes
project: — README, LICENSE, AGENTS.md, meta

Translations

License

By contributing, you agree that your contributions will be licensed under the MIT License.

3.9 KiB Raw Blame History Unescape Escape