pugz/docs/CLI_TEMPLATES_COMPLETE.md

CLI Templates Demo - Complete

✅ What's Been Created

A comprehensive demonstration of Pug templates for testing the pug-compile CLI tool, now located in src/tests/examples/cli-templates-demo/.

📁 Directory Structure

src/tests/examples/
├── demo/                    # HTTP server demo (existing)
└── cli-templates-demo/      # NEW: CLI compilation demo
    ├── layouts/
    │   ├── main.pug        # Full layout with header/footer
    │   └── simple.pug      # Minimal layout
    ├── partials/
    │   ├── header.pug      # Navigation header
    │   └── footer.pug      # Site footer
    ├── mixins/
    │   ├── buttons.pug     # Button components
    │   ├── forms.pug       # Form components
    │   ├── cards.pug       # Card components
    │   └── alerts.pug      # Alert components
    ├── pages/
    │   ├── index.pug       # Homepage
    │   ├── features-demo.pug    # All features
    │   ├── attributes-demo.pug  # All attributes
    │   └── about.pug       # About page
    ├── public/
    │   └── css/
    │       └── style.css   # Demo styles
    ├── generated/          # Compiled output (after running cli)
    └── README.md

🎯 What It Demonstrates

1. Layouts & Extends

• Main layout with header/footer includes
• Simple minimal layout
• Block system for content injection

2. Partials

• Reusable header with navigation
• Footer with links and sections

3. Mixins (4 files, 15+ mixins)

buttons.pug:

• btn(text, type) - Standard buttons
• btnIcon(text, icon, type) - Buttons with icons
• btnLink(text, href, type) - Link buttons
• btnCustom(text, attrs) - Custom attributes

forms.pug:

• input(name, label, type, required) - Text inputs
• textarea(name, label, rows) - Textareas
• select(name, label, options) - Dropdowns
• checkbox(name, label, checked) - Checkboxes

cards.pug:

• card(title, content) - Basic cards
• cardImage(title, image, content) - Image cards
• featureCard(icon, title, description) - Feature cards
• productCard(product) - Product cards

alerts.pug:

• alert(message, type) - Basic alerts
• alertDismissible(message, type) - Dismissible
• alertIcon(message, icon, type) - With icons

4. Pages

index.pug - Homepage:

• Hero section
• Feature grid using mixins
• Call-to-action sections

features-demo.pug - Complete Feature Set:

• All mixin usage examples
• Conditionals (if/else/unless)
• Loops (each with arrays, objects, indexes)
• Case/when statements
• Text interpolation and blocks
• Buffered/unbuffered code

attributes-demo.pug - All Pug Attributes: Demonstrates every feature from https://pugjs.org/language/attributes.html:

• Basic attributes
• JavaScript expressions
• Multiline attributes
• Quoted attributes (Angular-style (click))
• Attribute interpolation
• Unescaped attributes
• Boolean attributes
• Style attributes (string and object)
• Class attributes (array, object, conditional)
• Class/ID literals (.class #id)
• &attributes spreading
• Data attributes
• ARIA attributes
• Combined examples

about.pug - Standard Content:

• Tables
• Lists
• Links
• Regular content layout

🧪 Testing the CLI Tool

Compile All Pages

# From pugz root
zig build

# Compile templates
./zig-out/bin/cli --dir src/tests/examples/cli-templates-demo/pages \
                  --out src/tests/examples/cli-templates-demo/generated

Compile Single Template

./zig-out/bin/cli \
  src/tests/examples/cli-templates-demo/pages/index.pug \
  src/tests/examples/cli-templates-demo/generated/index.zig

Use Compiled Templates

const tpls = @import("cli-templates-demo/generated/root.zig");

const html = try tpls.pages_index.render(allocator, .{
    .pageTitle = "Home",
    .currentPage = "home",
    .year = "2024",
});
defer allocator.free(html);

📊 Feature Coverage

Runtime Mode (ViewEngine)

✅ 100% Feature Support

• All mixins work
• All includes/extends work
• All conditionals/loops work
• All attributes work

Compiled Mode (pug-compile)

Currently Supported:

• ✅ Tags and nesting
• ✅ Text interpolation #{var}
• ✅ Buffered code p= var
• ✅ Attributes (all types from demo)
• ✅ Doctypes
• ✅ Comments
• ✅ HTML escaping

In Progress:

• ⚠️ Conditionals (implemented but has buffer bugs)

Not Yet Implemented:

• ❌ Loops (each/while)
• ❌ Mixins
• ❌ Runtime includes (resolved at compile time only)
• ❌ Case/when

🎨 Styling

Complete CSS provided in public/css/style.css:

• Responsive layout
• Header/footer styling
• Component styles (buttons, forms, cards, alerts)
• Typography and spacing
• Utility classes

📚 Documentation

• Main README: src/tests/examples/cli-templates-demo/README.md
• Compiled Templates Guide: docs/COMPILED_TEMPLATES.md
• Status Report: COMPILED_TEMPLATES_STATUS.md

🔄 Workflow

1. Edit templates in cli-templates-demo/
2. Compile with the CLI tool
3. Check generated code in generated/
4. Test runtime rendering
5. Test compiled code execution
6. Compare outputs

💡 Use Cases

For Development

• Test all Pug features
• Verify CLI tool output
• Debug compilation issues
• Learn Pug syntax

For Testing

• Comprehensive test suite for CLI
• Regression testing
• Feature validation
• Output comparison

For Documentation

• Live examples of all features
• Reference implementations
• Best practices demonstration

🚀 Next Steps

To make compiled templates fully functional:

1. Fix conditional buffer management (HIGH PRIORITY)

   • Static content leaking outside conditionals
   • Need scoped buffer handling

2. Implement loops

   • Extract iterable field names
   • Generate Zig for loops
   • Handle each/else

3. Add mixin support

   • Generate Zig functions
   • Parameter handling
   • Block content

4. Comprehensive testing

   • Unit tests for each feature
   • Integration tests
   • Output validation

📝 Summary

Created a production-ready template suite with:

• 2 layouts
• 2 partials
• 4 mixin files (15+ mixins)
• 4 complete demo pages
• Full CSS styling
• Comprehensive documentation

All demonstrating every feature from the official Pug documentation, ready for testing both runtime and compiled modes.

The templates are now properly organized in src/tests/examples/cli-templates-demo/ and can serve as both a demo and a comprehensive test suite for the CLI compilation tool! 🎉