Genearte .zig verions of templates to use in production.

docs/DEMO_SERVER.md

@@ -0,0 +1,227 @@
+# Pugz Demo Server
+
+A simple HTTP server demonstrating Pugz template engine with both runtime and compiled template modes.
+
+## Quick Start
+
+### 1. Build Everything
+
+From the **pugz root directory** (not this demo directory):
+
+```bash
+cd /path/to/pugz
+zig build
+```
+
+This builds:
+- The `pugz` library
+- The `pug-compile` CLI tool (in `zig-out/bin/`)
+- All tests and benchmarks
+
+### 2. Build Demo Server
+
+```bash
+cd examples/demo
+zig build
+```
+
+### 3. Run Demo Server
+
+```bash
+zig build run
+```
+
+The server will start on `http://localhost:5882`
+
+## Using Compiled Templates (Optional)
+
+For maximum performance, you can pre-compile templates to Zig code:
+
+### Step 1: Compile Templates
+
+From the **pugz root**:
+
+```bash
+./zig-out/bin/pug-compile --dir examples/demo/views --out examples/demo/generated pages
+```
+
+This compiles all `.pug` files in `views/pages/` to Zig functions.
+
+### Step 2: Enable Compiled Mode
+
+Edit `src/main.zig` and set:
+
+```zig
+const USE_COMPILED_TEMPLATES = true;
+```
+
+### Step 3: Rebuild and Run
+
+```bash
+zig build run
+```
+
+## Project Structure
+
+```
+demo/
+├── build.zig              # Build configuration
+├── build.zig.zon          # Dependencies
+├── src/
+│   └── main.zig           # Server implementation
+├── views/                 # Pug templates (runtime mode)
+│   ├── layouts/
+│   │   └── main.pug
+│   ├── partials/
+│   │   ├── header.pug
+│   │   └── footer.pug
+│   └── pages/
+│       ├── home.pug
+│       └── about.pug
+└── generated/             # Compiled templates (after compilation)
+    ├── home.zig
+    ├── about.zig
+    ├── helpers.zig
+    └── root.zig
+```
+
+## Available Routes
+
+- `GET /` - Home page
+- `GET /about` - About page
+- `GET /simple` - Simple compiled template demo (if `USE_COMPILED_TEMPLATES=true`)
+
+## Runtime vs Compiled Templates
+
+### Runtime Mode (Default)
+- ✅ Full Pug feature support (extends, includes, mixins, loops)
+- ✅ Easy development - edit templates and refresh
+- ⚠️ Parses templates on every request
+
+### Compiled Mode
+- ✅ 10-100x faster (no runtime parsing)
+- ✅ Type-safe data structures
+- ✅ Zero dependencies in generated code
+- ⚠️ Limited features (no extends/includes/mixins yet)
+- ⚠️ Must recompile after template changes
+
+## Development Workflow
+
+### Runtime Mode (Recommended for Development)
+
+1. Edit `.pug` files in `views/`
+2. Refresh browser - changes take effect immediately
+3. No rebuild needed
+
+### Compiled Mode (Recommended for Production)
+
+1. Edit `.pug` files in `views/`
+2. Recompile: `../../../zig-out/bin/pug-compile --dir views --out generated pages`
+3. Rebuild: `zig build`
+4. Restart server
+
+## Dependencies
+
+- **pugz** - Template engine (from parent directory)
+- **httpz** - HTTP server ([karlseguin/http.zig](https://github.com/karlseguin/http.zig))
+
+## Troubleshooting
+
+### "unable to find module 'pugz'"
+
+Make sure you built from the pugz root directory first:
+
+```bash
+cd /path/to/pugz  # Go to root, not demo/
+zig build
+```
+
+### "File not found: views/..."
+
+Make sure you're running the server from the demo directory:
+
+```bash
+cd examples/demo
+zig build run
+```
+
+### Compiled templates not working
+
+1. Verify templates were compiled: `ls -la generated/`
+2. Check `USE_COMPILED_TEMPLATES` is set to `true` in `src/main.zig`
+3. Rebuild: `zig build`
+
+## Example: Adding a New Page
+
+### Runtime Mode
+
+1. Create `views/pages/contact.pug`:
+```pug
+extends ../layouts/main.pug
+
+block content
+  h1 Contact Us
+  p Email: hello@example.com
+```
+
+2. Add route in `src/main.zig`:
+```zig
+fn contactPage(app: *App, _: *httpz.Request, res: *httpz.Response) !void {
+    const html = app.view.render(res.arena, "pages/contact", .{
+        .siteName = "Demo Site",
+    }) catch |err| {
+        return renderError(res, err);
+    };
+    res.content_type = .HTML;
+    res.body = html;
+}
+
+// In main(), add route:
+server.router().get("/contact", contactPage);
+```
+
+3. Restart server and visit `http://localhost:5882/contact`
+
+### Compiled Mode
+
+1. Create simple template (no extends): `views/pages/contact.pug`
+```pug
+doctype html
+html
+  head
+    title Contact
+  body
+    h1 Contact Us
+    p Email: #{email}
+```
+
+2. Compile: `../../../zig-out/bin/pug-compile --dir views --out generated pages`
+
+3. Add route:
+```zig
+const templates = @import("templates");
+
+fn contactPage(app: *App, _: *httpz.Request, res: *httpz.Response) !void {
+    const html = try templates.pages_contact.render(res.arena, .{
+        .email = "hello@example.com",
+    });
+    res.content_type = .HTML;
+    res.body = html;
+}
+```
+
+4. Rebuild and restart
+
+## Performance Tips
+
+1. **Use compiled templates** for production (after development is complete)
+2. **Use ArenaAllocator** - Templates are freed all at once after response
+3. **Cache static assets** - Serve CSS/JS from CDN or static server
+4. **Keep templates simple** - Avoid complex logic in templates
+
+## Learn More
+
+- [Pugz Documentation](../../docs/)
+- [Pug Language Reference](https://pugjs.org/language/)
+- [Compiled Templates Guide](../cli-templates-demo/FEATURES_REFERENCE.md)
+- [Compatibility Matrix](../cli-templates-demo/PUGJS_COMPATIBILITY.md)