@getkist/action-nunjucks

Jinja/Nunjucks template rendering actions for kist.

Features

• 🎨 Render Nunjucks templates to files
• � Directory mode - batch render entire folders preserving structure
• 📝 Load context data from YAML/JSON files
• ⚙️ Configurable Nunjucks behaviors (autoescape, trim, lstrip)
• 🔤 Custom output encoding support
• 🚀 Useful for docs sites, static pages, and codegen

Installation

npm install --save-dev @getkist/action-nunjucks

Quick Start

Single File Mode

pipeline:
    stages:
        - name: render
          steps:
              - name: render-page
                action: TemplateRenderAction
                options:
                    templatePath: ./templates/page.njk
                    outputPath: ./dist/page.html
                    context:
                        title: "Welcome"

Directory Mode

Render all templates in a directory while preserving folder structure:

pipeline:
    stages:
        - name: render
          steps:
              - name: render-templates
                action: TemplateRenderAction
                options:
                    inputDir: ./src/templates
                    outputDir: ./dist
                    pattern: "**/*.html.jinja"
                    excludePatterns:
                        - "_*.jinja"
                        - "partials/**"
                    stripExtension: ".jinja"
                    context:
                        siteName: "My Site"

This renders:

• src/templates/index.html.jinja → dist/index.html
• src/templates/about/team.html.jinja → dist/about/team.html
• Skips _base.jinja and partials/ files

Documentation

• Usage Guide - YAML and programmatic examples
• Configuration - All available options
• Examples - Real-world use cases
• API Reference - Generated TypeDoc documentation
• Troubleshooting - Common issues and solutions
• Performance Guide - Tips for optimization

Actions

TemplateRenderAction

Renders Nunjucks templates with optional context files and Nunjucks configuration.

Single File Mode Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | templatePath | string | Yes | Path to template file | | outputPath | string | Yes | Output file path | | context | object | No | Template context data | | contextFiles | string[] | No | YAML/JSON files to merge | | searchPaths | string[] | No | Template search paths for includes | | autoescape | boolean | No | Enable HTML escaping | | trimBlocks | boolean | No | Trim trailing newlines from blocks | | lstripBlocks | boolean | No | Strip leading whitespace from blocks | | outputEncoding | string | No | File encoding (default: utf8) |

Directory Mode Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | inputDir | string | Yes | Source directory containing templates | | outputDir | string | Yes | Output directory for rendered files | | pattern | string | No | Glob pattern (default: **/*.html.jinja) | | excludePatterns | string[] | No | Patterns to exclude (e.g., partials) | | stripExtension | string | No | Extension to remove (default: .jinja) | | context | object | No | Shared context for all templates | | contextFiles | string[] | No | YAML/JSON files to merge | | searchPaths | string[] | No | Template search paths for includes | | autoescape | boolean | No | Enable HTML escaping | | trimBlocks | boolean | No | Trim trailing newlines from blocks | | lstripBlocks | boolean | No | Strip leading whitespace from blocks | | outputEncoding | string | No | File encoding (default: utf8) |

Development

npm run build        # Compile TypeScript
npm run test         # Run tests
npm run lint         # Check code quality
npm run docs         # Generate API documentation
npm run format       # Format code with Prettier

Requirements

• Node.js >= 20.0.0
• npm >= 10.0.0

License

MIT