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])
103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# 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
|
||
|
||
1. 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
|
||
2. Edit each `.tmpl` file in `themes/<your-style-name>/` with your unique visual design
|
||
3. 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
|
||
4. 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](https://github.com/go-gitea/gitea) 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:
|
||
|
||
1. Check that all referenced Go template variables exist — compare against the Gitea source mail templates
|
||
2. Verify translation keys match Gitea's locale files
|
||
3. Confirm `.DisplayName` isn't used in templates that lack it
|
||
4. Regenerate the preview: `cd tools && go run . preview all`
|
||
5. 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)
|
||
|
||
1. Run `cd tools && go run . preview all` to generate rendered data
|
||
2. Open `preview/index.html` directly in a browser — no server needed
|
||
3. 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)
|
||
|
||
```bash
|
||
cd tools && go run . dev
|
||
# → http://localhost:3456
|
||
```
|
||
|
||
- Watches `themes/**/*.tmpl` — auto-rebuilds on save
|
||
- Runs [Juice](https://github.com/Automattic/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
|
||
|
||
- [English](CONTRIBUTING.md)
|
||
- [Simplified Chinese](docs/CONTRIBUTING.zh-CN.md)
|
||
- [Traditional Chinese](docs/CONTRIBUTING.zh-TW.md)
|
||
- [Russian](docs/CONTRIBUTING.ru.md)
|
||
- [Japanese](docs/CONTRIBUTING.ja.md)
|
||
- [Korean](docs/CONTRIBUTING.ko.md)
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
By contributing, you agree that your contributions will be licensed under the MIT License.
|