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 `