docs: update all docs with dev server, live reload, Juice inlining
- README.md: restructure Preview section into Static + Dev modes with feature comparison table; mention juice inlining and live reload - CONTRIBUTING.md: update Development Setup with Go/Node.js requirements, static vs dev preview workflows, Juice reference - AGENTS.md: add dev command to subcommand list, document tools/server/ directory, update Build Tool section - docs/CONTRIBUTING.*.md (5 languages): add dev server section, Node.js requirement, live reload description - docs/README.*.md (5 languages): add dev mode to Preview section - docs/images/README.md: update capture instructions for dev server Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
KenanZhuandClaude Opus 4.8 committed
1 parent
13c49d2087
commit
7724b4806c
14 files changed
+168
-43
No files matched your search
@@ -48,16 +48,19 @@ docs/ # Multi-language documentation
|
||||
|
||||
### Preview System
|
||||
- `preview/index.html` loads `preview/rendered.js` (pre-rendered by Go) and displays in iframes
|
||||
- Supports theme switching, template type switching, client simulation (Modern/Gmail/Outlook/Raw), and viewport toggle (Desktop 1386x780 / Mobile 390x780)
|
||||
- `REGISTRY` and `PARAMS` are auto-generated from `templates_config.json` by the build tool — no manual syncing needed
|
||||
- Supports theme/template switching, client simulation (Modern/Gmail/Outlook/Raw), and viewport toggle (Desktop 1386x780 / Mobile 390x780)
|
||||
- `REGISTRY` and `PARAMS` are auto-generated from `templates_config.json` — no manual syncing needed
|
||||
- Static preview (open `index.html` directly) provides approximate client simulation
|
||||
- Dev server (`go run . dev`) provides accurate rendering via Juice CSS inlining + live reload
|
||||
|
||||
### Build Tool
|
||||
- `tools/tools.go` is the main entry point for the modular CLI
|
||||
- Subcommands: `list`, `create`, `delete`, `preview`
|
||||
- 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)
|
||||
- `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
|
||||
|
||||
+16
-8
@@ -40,21 +40,29 @@ Documentation updates, preview screenshots, installation guides, and translation
|
||||
|
||||
## Development Setup
|
||||
|
||||
No build tools or dependencies are needed — these are raw Go HTML templates.
|
||||
- **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
|
||||
### Previewing Locally (Static)
|
||||
|
||||
1. Open `preview/index.html` directly in a browser — no server needed
|
||||
2. Use the theme switcher, template selector, and client mode toggles to review designs
|
||||
3. Toggle between Modern, Gmail, Outlook, and Raw source modes to verify degradation
|
||||
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
|
||||
|
||||
### Regenerating Previews
|
||||
> Static Gmail/Outlook simulation is approximate. Use dev mode for accurate rendering.
|
||||
|
||||
### Dev Server (Live Reload + CSS Inlining)
|
||||
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
This renders all templates (themes auto-discovered from the themes/ directory) using Go's native `html/template` package and writes the output to `preview/rendered.js`. The `--folder` and `--config` flags default to `../themes` and `./data/templates_config.json` respectively — override them only when using a custom layout.
|
||||
- Watches `themes/**/*.tmpl` — auto-rebuilds on save
|
||||
- Runs [Juice](https://github.com/Automattic/juice) to inline `<style>` into `style=""` attributes
|
||||
- Adds Outlook-compatible `bgcolor`/`width` HTML attributes
|
||||
- Pushes live reload to browser via WebSocket
|
||||
- Terminal output: `themes/aurora/mail/repo/release.tmpl edited` → `[rebuild] done in 480ms`
|
||||
|
||||
### Integration Testing
|
||||
|
||||
|
||||
@@ -78,28 +78,45 @@ Send a test email from the Gitea admin panel:
|
||||
|
||||
## Preview
|
||||
|
||||
A live preview tool is included to browse all styles and email types without deploying to a Gitea instance.
|
||||
Two modes are available — a zero-dependency static preview for quick checks, and a live-reload dev server for design work.
|
||||
|
||||
### Quick Start
|
||||
### Static Preview
|
||||
|
||||
First, generate the preview data (requires Go):
|
||||
Generate the preview data once (Go only), then open in a browser:
|
||||
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
open preview/index.html # no server needed
|
||||
```
|
||||
|
||||
Then open `preview/index.html` directly in a browser. No server required.
|
||||
> Gmail/Outlook simulation in static mode is approximate. Use dev mode for accurate CSS inlining.
|
||||
|
||||
> `preview/rendered.js` is generated and git-ignored. Re-run `cd tools && go run . preview all` after modifying templates. Use `cd tools && go run .` to see all commands (list, create, delete, preview). Most flags have sensible defaults — just `go run . create <name>` or `go run . preview all` works out of the box.
|
||||
### Dev Server (Live Reload + Juice CSS Inlining)
|
||||
|
||||
Start a development server that watches for `.tmpl` changes, auto-rebuilds, inlines CSS for email client compatibility, and pushes live updates to the browser:
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev # requires Node.js
|
||||
open http://localhost:3456
|
||||
```
|
||||
|
||||
| Capability | Static | Dev |
|
||||
|-----------|--------|-----|
|
||||
| Go template rendering | ✅ | ✅ |
|
||||
| Theme/template switching | ✅ | ✅ |
|
||||
| Juice CSS inlining | — | ✅ |
|
||||
| Outlook `bgcolor` attrs | — | ✅ |
|
||||
| Live reload on save | — | ✅ |
|
||||
| Node.js required | — | ✅ |
|
||||
|
||||
### Features
|
||||
|
||||
- Theme switcher — toggle between all 10 visual styles
|
||||
- Template switcher — browse all 11 email types
|
||||
- Client simulation — Modern, Gmail (no `<style>`), Outlook Desktop, Raw source
|
||||
- Viewport toggle — Desktop (1386x780) / Mobile (390x780)
|
||||
- Parameter panel — view template variables and mock data per email type
|
||||
- Keyboard shortcuts — `←→` templates, `d` desktop, `m` mobile
|
||||
- Theme switcher — browse all 10 visual styles
|
||||
- Template switcher — all 11 email types
|
||||
- Client simulation — Modern, Gmail, Outlook, Raw Source
|
||||
- Viewport toggle — Desktop 1386×780 / Mobile 390×780
|
||||
- Parameter panel — mock data per email type
|
||||
- Keyboard shortcuts — `←→` templates, `d`/`m` viewport
|
||||
|
||||
---
|
||||
|
||||
|
||||
+15
-2
@@ -30,11 +30,24 @@
|
||||
|
||||
## 開発セットアップ
|
||||
|
||||
### ローカルプレビュー
|
||||
- **Go 1.21+** テンプレートレンダリングとCLI用
|
||||
- **Node.js 18+**（任意）開発サーバーとJuice CSSインライン用
|
||||
|
||||
### ローカルプレビュー（静的）
|
||||
|
||||
1. データを生成: `cd tools && go run . preview all`
|
||||
2. `preview/index.html` をブラウザで開く
|
||||
3. Modern, Gmail, Outlook, Raw source を切り替えて確認
|
||||
|
||||
> 静的Gmail/Outlookシミュレーションは参考用です。正確なレンダリングにはdevモードを使用してください。
|
||||
|
||||
### 開発サーバー（ライブリロード + CSSインライン）
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
`.tmpl` ファイルを編集すると自動的に再構築されブラウザに反映されます。
|
||||
|
||||
### 結合テスト
|
||||
|
||||
|
||||
+15
-2
@@ -30,11 +30,24 @@
|
||||
|
||||
## 개발 설정
|
||||
|
||||
### 로컬 프리뷰
|
||||
- **Go 1.21+** 템플릿 렌더링 및 CLI 도구
|
||||
- **Node.js 18+** (선택) 개발 서버 및 Juice CSS 인라인
|
||||
|
||||
### 로컬 프리뷰 (정적)
|
||||
|
||||
1. 데이터 생성: `cd tools && go run . preview all`
|
||||
2. `preview/index.html`을 브라우저에서 열기
|
||||
3. Modern, Gmail, Outlook, Raw source 모드 전환 확인
|
||||
|
||||
> 정적 Gmail/Outlook 시뮬레이션은 참고용입니다. 정확한 렌더링은 dev 모드를 사용하세요.
|
||||
|
||||
### 개발 서버 (실시간 리로드 + CSS 인라인)
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
`.tmpl` 파일 수정 시 자동 재빌드되어 브라우저에 반영됩니다.
|
||||
|
||||
### 통합 테스트
|
||||
|
||||
|
||||
+16
-3
@@ -30,11 +30,24 @@
|
||||
|
||||
## Настройка разработки
|
||||
|
||||
### Локальный предпросмотр
|
||||
- **Go 1.21+** для рендеринга шаблонов и CLI
|
||||
- **Node.js 18+** (опционально) для сервера разработки с Juice CSS
|
||||
|
||||
### Локальный предпросмотр (статический)
|
||||
|
||||
1. Сгенерируйте данные: `cd tools && go run . preview all`
|
||||
2. Откройте `preview/index.html` в браузере
|
||||
3. Переключайте Modern, Gmail, Outlook, Raw source для проверки
|
||||
2. Откройте `preview/index.html` в браузере — сервер не нужен
|
||||
|
||||
> Статическая симуляция Gmail/Outlook приблизительна. Используйте dev-режим для точного рендеринга.
|
||||
|
||||
### Сервер разработки (live reload + CSS инлайн)
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
При изменении `.tmpl` файлов автоматически пересобирает и обновляет браузер.
|
||||
|
||||
### Интеграционное тестирование
|
||||
|
||||
|
||||
@@ -34,13 +34,24 @@
|
||||
|
||||
## 开发环境
|
||||
|
||||
无需构建工具或依赖。
|
||||
- **Go 1.21+** 用于模板渲染和 CLI 工具
|
||||
- **Node.js 18+**（可选）用于实时开发服务器与 Juice CSS 内联
|
||||
|
||||
### 本地预览
|
||||
### 本地预览（静态）
|
||||
|
||||
1. 先生成预览数据：`cd tools && go run . preview all`
|
||||
2. 在浏览器中打开 `preview/index.html`
|
||||
3. 在 Modern、Gmail、Outlook、Raw source 模式间切换验证效果
|
||||
2. 在浏览器中打开 `preview/index.html` — 无需服务器
|
||||
|
||||
> 静态 Gmail/Outlook 模拟仅供参考，使用 dev 模式可获得准确的 CSS 内联渲染。
|
||||
|
||||
### 开发服务器（实时重载 + CSS 内联）
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
修改 `.tmpl` 文件后自动重建并推送至浏览器。
|
||||
|
||||
### 集成测试
|
||||
|
||||
|
||||
@@ -34,13 +34,24 @@
|
||||
|
||||
## 開發環境
|
||||
|
||||
無需建置工具或依賴。
|
||||
- **Go 1.21+** 用於模板渲染與 CLI 工具
|
||||
- **Node.js 18+**（可選）用於即時開發伺服器與 Juice CSS 內聯
|
||||
|
||||
### 本機預覽
|
||||
### 本機預覽（靜態）
|
||||
|
||||
1. 先生成預覽資料：`cd tools && go run . preview all`
|
||||
2. 在瀏覽器中開啟 `preview/index.html`
|
||||
3. 在 Modern、Gmail、Outlook、Raw source 模式間切換驗證效果
|
||||
2. 在瀏覽器中開啟 `preview/index.html` — 無需伺服器
|
||||
|
||||
> 靜態 Gmail/Outlook 模擬僅供參考，使用 dev 模式可獲得準確的 CSS 內聯渲染。
|
||||
|
||||
### 開發伺服器（即時重載 + CSS 內聯）
|
||||
|
||||
```bash
|
||||
cd tools && go run . dev
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
修改 `.tmpl` 檔案後自動重建並推送至瀏覽器。
|
||||
|
||||
### 整合測試
|
||||
|
||||
|
||||
@@ -36,11 +36,18 @@ systemctl restart gitea
|
||||
|
||||
## プレビュー
|
||||
|
||||
**静的モード:**
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
```
|
||||
その後 `preview/index.html` を開く。
|
||||
|
||||
**開発サーバー（ライブリロード + Juice CSSインライン）:**
|
||||
```bash
|
||||
cd tools && go run . dev # Node.jsが必要です
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
## 互換性
|
||||
|
||||
- **Gitea 1.21+**, 100%互換, 組み込み関数のみ
|
||||
|
||||
@@ -36,11 +36,18 @@ systemctl restart gitea
|
||||
|
||||
## 프리뷰
|
||||
|
||||
**정적 모드:**
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
```
|
||||
그런 다음 `preview/index.html` 열기.
|
||||
|
||||
**개발 서버 (실시간 리로드 + Juice CSS 인라인):**
|
||||
```bash
|
||||
cd tools && go run . dev # Node.js 필요
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
## 호환성
|
||||
|
||||
- **Gitea 1.21+**, 100% 호환, 내장 함수만 사용
|
||||
|
||||
@@ -36,11 +36,18 @@ systemctl restart gitea
|
||||
|
||||
## Предпросмотр
|
||||
|
||||
**Статический режим:**
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
```
|
||||
Затем откройте `preview/index.html`.
|
||||
|
||||
**Dev-сервер (live reload + Juice CSS inline):**
|
||||
```bash
|
||||
cd tools && go run . dev # требуется Node.js
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
## Совместимость
|
||||
|
||||
- **Gitea 1.21+**, 100% совместимость, только встроенные функции
|
||||
|
||||
@@ -50,11 +50,18 @@ systemctl restart gitea
|
||||
|
||||
## 预览
|
||||
|
||||
**静态模式：**
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
```
|
||||
然后打开 `preview/index.html`。
|
||||
|
||||
**开发服务器（实时重载 + Juice CSS 内联）：**
|
||||
```bash
|
||||
cd tools && go run . dev # 需要 Node.js
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 兼容性
|
||||
|
||||
@@ -50,11 +50,18 @@ systemctl restart gitea
|
||||
|
||||
## 預覽
|
||||
|
||||
**靜態模式：**
|
||||
```bash
|
||||
cd tools && go run . preview all
|
||||
```
|
||||
然後開啟 `preview/index.html`。
|
||||
|
||||
**開發伺服器（即時重載 + Juice CSS 內聯）：**
|
||||
```bash
|
||||
cd tools && go run . dev # 需要 Node.js
|
||||
# → http://localhost:3456
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相容性
|
||||
|
||||
@@ -11,8 +11,9 @@ neon.png mono.png terra.png ink.png aurora.png
|
||||
|
||||
## How to Capture
|
||||
|
||||
1. Run `cd tools && go run . preview all` from the project root
|
||||
2. Open `preview/index.html` in a browser
|
||||
3. For each style, select the "Activate Account" template and "Modern" client mode
|
||||
4. Take a screenshot of the rendered email (600px width recommended)
|
||||
5. Save as `<style-name>.png` in this directory
|
||||
1. Start the dev server: `cd tools && go run . dev` (opens http://localhost:3456)
|
||||
2. For each style, select the "Activate Account" template and "Modern" client mode
|
||||
3. Take a screenshot of the rendered email (600px width recommended)
|
||||
4. Save as `<style-name>.png` in this directory
|
||||
|
||||
> For static preview, run `cd tools && go run . preview all` then open `preview/index.html` directly.
|
||||
Reference in new issue
Block a user