From 7724b4806c980a20f88d8533b7b6a33051f58b78 Mon Sep 17 00:00:00 2001
From: KenanZhu <3471685733@qq.com>
Date: Thu, 4 Jun 2026 13:58:15 +0800
Subject: [PATCH] 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>
---
 AGENTS.md                  | 11 +++++++----
 CONTRIBUTING.md            | 24 +++++++++++++++--------
 README.md                  | 39 +++++++++++++++++++++++++++-----------
 docs/CONTRIBUTING.ja.md    | 17 +++++++++++++++--
 docs/CONTRIBUTING.ko.md    | 17 +++++++++++++++--
 docs/CONTRIBUTING.ru.md    | 19 ++++++++++++++++---
 docs/CONTRIBUTING.zh-CN.md | 19 +++++++++++++++----
 docs/CONTRIBUTING.zh-TW.md | 19 +++++++++++++++----
 docs/README.ja.md          |  7 +++++++
 docs/README.ko.md          |  7 +++++++
 docs/README.ru.md          |  7 +++++++
 docs/README.zh-CN.md       |  7 +++++++
 docs/README.zh-TW.md       |  7 +++++++
 docs/images/README.md      | 11 ++++++-----
 14 files changed, 168 insertions(+), 43 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6407e67..84ac64e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e1e8578..09a5fd9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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
 
diff --git a/README.md b/README.md
index c1e0bc9..9cb62c0 100644
--- a/README.md
+++ b/README.md
@@ -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
 
 ---
 
diff --git a/docs/CONTRIBUTING.ja.md b/docs/CONTRIBUTING.ja.md
index b3f148f..c9da712 100644
--- a/docs/CONTRIBUTING.ja.md
+++ b/docs/CONTRIBUTING.ja.md
@@ -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` ファイルを編集すると自動的に再構築されブラウザに反映されます。
 
 ### 結合テスト
 
diff --git a/docs/CONTRIBUTING.ko.md b/docs/CONTRIBUTING.ko.md
index 1af94be..941829a 100644
--- a/docs/CONTRIBUTING.ko.md
+++ b/docs/CONTRIBUTING.ko.md
@@ -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` 파일 수정 시 자동 재빌드되어 브라우저에 반영됩니다.
 
 ### 통합 테스트
 
diff --git a/docs/CONTRIBUTING.ru.md b/docs/CONTRIBUTING.ru.md
index 741b471..2d5330d 100644
--- a/docs/CONTRIBUTING.ru.md
+++ b/docs/CONTRIBUTING.ru.md
@@ -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` файлов автоматически пересобирает и обновляет браузер.
 
 ### Интеграционное тестирование
 
diff --git a/docs/CONTRIBUTING.zh-CN.md b/docs/CONTRIBUTING.zh-CN.md
index 81a1605..7965cc2 100644
--- a/docs/CONTRIBUTING.zh-CN.md
+++ b/docs/CONTRIBUTING.zh-CN.md
@@ -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` 文件后自动重建并推送至浏览器。
 
 ### 集成测试
 
diff --git a/docs/CONTRIBUTING.zh-TW.md b/docs/CONTRIBUTING.zh-TW.md
index 8c67608..960d01d 100644
--- a/docs/CONTRIBUTING.zh-TW.md
+++ b/docs/CONTRIBUTING.zh-TW.md
@@ -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` 檔案後自動重建並推送至瀏覽器。
 
 ### 整合測試
 
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 7c38962..4a0e9bd 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -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%互換, 組み込み関数のみ
diff --git a/docs/README.ko.md b/docs/README.ko.md
index 48651fa..7051420 100644
--- a/docs/README.ko.md
+++ b/docs/README.ko.md
@@ -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% 호환, 내장 함수만 사용
diff --git a/docs/README.ru.md b/docs/README.ru.md
index cd989ee..e204a86 100644
--- a/docs/README.ru.md
+++ b/docs/README.ru.md
@@ -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% совместимость, только встроенные функции
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 317c72e..bde39dc 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -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
+```
+
 ---
 
 ## 兼容性
diff --git a/docs/README.zh-TW.md b/docs/README.zh-TW.md
index 4c8252c..40b86e7 100644
--- a/docs/README.zh-TW.md
+++ b/docs/README.zh-TW.md
@@ -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
+```
+
 ---
 
 ## 相容性
diff --git a/docs/images/README.md b/docs/images/README.md
index 3a9107f..849296a 100644
--- a/docs/images/README.md
+++ b/docs/images/README.md
@@ -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.