Extend MiniJinja with Additional Utility Functions (sha256, base64)

[mikkeldamsgaard]

Extend MiniJinja with Additional Utility Functions (sha256, base64)

Summary

We want to enhance the templating capabilities in Initium by adding custom utility functions to the MiniJinja environment. These functions should be chainable and easy to extend in the future. The new functions should include:

• sha256 – compute a SHA-256 hash and optionally return both a hex string and a byte array representation.
• base64 – both encoding and decoding capabilities.

These functions should be clearly separated into a dedicated implementation module to make it easy for contributors to add more functions over time.

Background

MiniJinja supports adding custom functions to its environment via add_function, allowing Rust functions to be exposed in templates. oai_citation:0‡Docs.rs However, the default built-ins do not include SHA-256 or Base64 utilities, which are useful for things like checksums, templated secrets, or content fingerprinting.

Requirements

1. New Utility Module

   • Create a dedicated module (e.g., templatefuncs, jinja_ext, or similar) for additional MiniJinja functions.
   • Keep this module separate from core template code to encourage future growth.

2. Chainable Function Design

   • Functions exposed to templates should be composable and chainable.
   • Example usage in templates:

     {{ "example input" | sha256("hex") | base64 }}
     

3. Function Definitions

   • sha256(input, mode?)
     • Compute the SHA-256 of input.
     • Optional parameter for output format: "hex" or "bytes"
   • base64_encode(input)
     • Return the Base64 encoding of input.
   • base64_decode(input)
     • Return the decoded string or data from Base64.

4. Template Examples

   • Add examples demonstrating how to use these functions in MiniJinja templates used by Initium.

5. Documentation

   • Document the new functions in the relevant documentation (e.g., docs/templating.md or README).
   • Explain usage patterns and expected behavior.

6. Tests

   • Add unit tests covering:
     • Correctness of SHA-256 outputs for known values
     • Base64 encode/decode roundtrip
     • Error handling for invalid Base64 input
     • Template integration tests using MiniJinja with these functions

Deliverables

• A separate module for MiniJinja utility functions
• Implementation of sha256, base64_encode, and base64_decode
• Integration with the MiniJinja environment in Initium
• Examples of usage in templates
• Documentation covering the new functions
• Tests verifying functionality and chainability

Acceptance Criteria

• The new functions are available in all Initium templates via the MiniJinja environment.
• The functions can be chained in template expressions.
• Tests cover all expected returns and edge cases.
• Code organization clearly separates core template logic and extended utility functions.