npm package: @getkist/action-nunjucks
Description: Jinja/Nunjucks template rendering actions for kist with single-file and directory mode support
Author: kist
Latest version: 2.0.14

# @getkist/action-nunjucks

[![npm version](https://img.shields.io/npm/v/@getkist/action-nunjucks.svg)](https://www.npmjs.com/package/@getkist/action-nunjucks)
[![npm downloads](https://img.shields.io/npm/dm/@getkist/action-nunjucks.svg)](https://www.npmjs.com/package/@getkist/action-nunjucks)
[![Node.js version](https://img.shields.io/node/v/@getkist/action-nunjucks.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test Status](https://github.com/getkist/kist-action-nunjucks/workflows/Test/badge.svg)](https://github.com/getkist/kist-action-nunjucks/actions)
[![Codecov Coverage](https://img.shields.io/codecov/c/github/getkist/action-nunjucks.svg)](https://codecov.io/gh/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

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

## Quick Start

### Single File Mode

```yaml
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:

```yaml
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](./doc/usage.md)** - YAML and programmatic examples
- **[Configuration](./doc/configuration.md)** - All available options
- **[Examples](./doc/examples.md)** - Real-world use cases
- **[API Reference](./doc/api.md)** - Generated TypeDoc documentation
- **[Troubleshooting](./doc/troubleshooting.md)** - Common issues and solutions
- **[Performance Guide](./doc/performance.md)** - 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

```bash
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