makejinja

🌟 GitHub Project 🌟

makejinja demonstration

makejinja can be used to automatically generate files from Jinja templates. It is conceptually similar to Ansible templates since both are built on top of Jinja. However, makejinja is a standalone tool that can be used without Ansible and offers some advanced features like custom plugins.

A popular use case is generating config files for Home Assistant: Using the same Jinja language that Home Assistant's built-in templates use, you can greatly simplify your configuration management. makejinja's custom delimiter support prevents conflicts with Home Assistant's own template syntax, while file-specific data loading enables modular dashboard and automation generation. Our comprehensive Home Assistant example demonstrates dashboard generation with custom plugins, multiple data sources, and advanced template organization.

Key Features

  • Multi-Source Data Integration: Load variables from YAML, TOML, and Python files, with support for file-specific data sources and runtime variable injection.
  • Custom Template Delimiters: Configure Jinja delimiters (e.g., <% %> instead of {{ }}) to avoid conflicts with target file formats like Home Assistant, Kubernetes, or Terraform.
  • Flexible Directory Processing: Process multiple input directories with complex nested structures, preserving hierarchy while applying powerful template transformations.
  • Extensible Plugin System: Create custom plugins with filters, functions, and path filtering logic for specialized requirements.
  • Production-Ready: Comprehensive CLI interface, configuration file support, and Python library API for seamless workflow integration.

Use Cases

  • Configuration Management: Generate environment-specific configs (dev/staging/prod) from shared templates with different data sources.
  • Home Assistant Dashboards: Create complex dashboards and automations using Jinja syntax without conflicts. See our complete example.
  • Infrastructure as Code: Generate Kubernetes manifests, Terraform modules, or Docker Compose files with consistent patterns across environments.
  • Web Development: Generate HTML pages, CSS files, or JavaScript configs from data sources for static sites or multi-tenant applications.
  • Database Schemas: Create SQL migration scripts, database configurations, or ORM models based on structured schema definitions.
  • Network Configuration: Generate router configs, firewall rules, or network device settings from centralized network topology data.
  • Monitoring & Alerting: Create Grafana dashboards, Prometheus rules, or alerting configurations from service inventories.
  • Documentation & CI/CD: Create project docs, API specifications, or pipeline definitions from structured data sources.

Installation

The tool is written in Python and can be installed via uv, nix, and docker. It can be used as a CLI tool or as a Python library.

UV

makejinja is available on PyPI and can be installed via uv:

uv tool install makejinja
makejinja -i ./input -o ./output

Nix

makejinja is packaged in nixpkgs. To use the most recent version, you can run it via nix run:

nix run github:mirkolenz/makejinja -- -i ./input -o ./output

Alternatively, you can add this repository as an input to your flake and use makejinja.packages.${system}.default.

Docker

We automatically publish an image to the GitHub Container Registry. To use it, mount a directory to the container and pass the options as the command:

docker run --rm -v $(pwd)/data:/data ghcr.io/mirkolenz/makejinja:latest -i /data/input -o /data/output

Usage in Terminal / Command Line

In its default configuration, makejinja searches the input directory recursively for files ending in .jinja. It then renders these files and writes them to the output directory, preserving the directory structure. Our documentation contains a detailed description of all options and can also be accessed via makejinja --help.

Usage as a Library

While mainly intended to be used as a command line tool, makejinja can also be from Python directly.

 1"""
 2**[🌟 GitHub Project 🌟](https://github.com/mirkolenz/makejinja)**
 3
 4![makejinja demonstration](../../assets/demo.gif)
 5
 6.. include:: ../../README.md
 7   :start-after: <!-- PDOC_START -->
 8
 9## Usage as a Library
10
11While mainly intended to be used as a command line tool, makejinja can also be from Python directly.
12"""
13
14from . import cli, config, plugin
15from .app import makejinja
16
17loader = plugin
18
19__all__ = ["makejinja", "config", "plugin", "loader", "cli"]
def makejinja(config: makejinja.config.Config): 
38def makejinja(config: Config):
39    """makejinja can be used to automatically generate files from [Jinja templates](https://jinja.palletsprojects.com/en/3.1.x/templates/)."""
40
41    for cmd in config.exec_pre:
42        exec(cmd)
43
44    for path in config.import_paths:
45        sys.path.append(str(path.resolve()))
46
47    data = load_data(config)
48
49    if config.output.is_dir() and config.clean:
50        log(f"Remove output '{config.output}'", config)
51
52        shutil.rmtree(config.output)
53
54    if not single_input_output_file(config):
55        config.output.mkdir(exist_ok=True, parents=True)
56
57    env = init_jinja_env(config, data)
58    plugins: list[Plugin] = []
59
60    for plugin_name in itertools.chain(config.plugins, config.loaders):
61        plugins.append(load_plugin(plugin_name, env, data, config))
62
63    plugin_path_filters: list[PathFilter] = []
64
65    for plugin in plugins:
66        if hasattr(plugin, "path_filters"):
67            plugin_path_filters.extend(plugin.path_filters())
68
69    # Save rendered files to avoid duplicate work
70    # Even if two files are in two separate dirs, they will have the same template name (i.e., relative path)
71    # and thus only the first one will be rendered every time
72    # Key: output_path, Value: input_path
73    rendered_files: dict[Path, Path] = {}
74
75    # Save rendered dirs to later copy metadata
76    # Key: output_path, Value: input_path
77    rendered_dirs: dict[Path, Path] = {}
78
79    for user_input_path in config.inputs:
80        if user_input_path.is_file() or user_input_path == STDIN_PATH:
81            handle_input_file(user_input_path, config, env, rendered_files)
82        elif user_input_path.is_dir():
83            handle_input_dir(
84                user_input_path,
85                config,
86                env,
87                rendered_files,
88                rendered_dirs,
89                plugin_path_filters,
90            )
91
92    postprocess_rendered_dirs(config, rendered_dirs)
93
94    for cmd in config.exec_post:
95        exec(cmd)

makejinja can be used to automatically generate files from Jinja templates.