template

Kind	kit
Capabilities	file
Categories	template-engine web text-processing
Keywords	template mustache html text rendering

Simple templating engine for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`docs/.keep`	Placeholder for generated documentation
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and dependencies
`src/template.kit`	Kit Template - full-featured templating engine
`tests/template.test.kit`	Tests for template rendering
`tests/types.test.kit`	Tests for template types

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-template.git

Usage

import Kit.Template as Template

main = fn =>
  # Render simple variables
  ctx = Template.empty-context
    |> Template.with-string "name" "Alice"
    |> Template.with-string "place" "Kit"

  match Template.render "Hello, {{name}}! Welcome to {{place}}." ctx
    | Ok result -> println result
    | Err err -> println "Error: ${err}"

  # Render conditionals
  admin-ctx = Template.empty-context
    |> Template.with-bool "admin" true
    |> Template.with-string "role" "admin"

  match Template.render "{{#if admin}}Signed in as {{role}}{{#else}}Guest{{/if}}" admin-ctx
    | Ok result -> println result
    | Err err -> println "Error: ${err}"

  # Render loops
  list-ctx = Template.empty-context
    |> Template.with-list "items"["apple", "banana", "cherry"]

  match Template.render "Items: {{#each items}}{{.}} {{/each}}" list-ctx
    | Ok result -> println result
    | Err err -> println "Error: ${err}"

  # Render partials
  partials = Template.empty-partials
    |> Template.with-partial "header" "<h1>{{title}}</h1>"

  partial-ctx = Template.empty-context
    |> Template.with-string "title" "Welcome"

  match Template.render-with-partials "{{> header}}<p>Body</p>" partial-ctx partials
    | Ok result -> println result
    | Err err -> println "Error: ${err}"

  # Render a page inside a layout
  page = "{{#content-for scripts}}<script src=\"/page.js\"></script>{{/content-for}}<main>{{body}}</main>"
  layout = "<html><body>{{{content}}}{{yield scripts}}</body></html>"
  layout-ctx = Template.empty-context
    |> Template.with-string "body" "Page content"

  match Template.render-with-layout layout page layout-ctx
    | Ok result -> println result
    | Err err -> println "Error: ${err}"

main

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Type check examples in examples/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc src/template.kit

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/template/, making it available for import as Kit.Template in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`TemplateError`

Template error type with specific variants for different failure modes.

Variants

TemplateParseError {message}

TemplateRenderError {message}

`ContextValue`

Value types for template context variables.

Variants

StringVal {String}

BoolVal {Bool}

ListVal {List, ContextValue}

ObjectVal {List}

NullVal

`empty-context`

Creates an empty template context.

List (String, ContextValue)

`empty-partials`

Creates an empty partials collection.

List (String, String)

`with-partial`

Adds a partial template to the partials collection.

List (String, String) -> NonEmptyString -> String -> List (String, String)

`empty-content-blocks`

Creates an empty content blocks collection.

List (String, String)

`with-content-block`

Adds a content block to the collection.

List (String, String) -> NonEmptyString -> String -> List (String, String)

`with-string`

Adds a string value to the template context.

List (String, ContextValue) -> NonEmptyString -> String -> List (String, ContextValue)

`with-bool`

Adds a boolean value to the template context.

List (String, ContextValue) -> NonEmptyString -> Bool -> List (String, ContextValue)

`with-list`

Adds a list of strings to the template context.

List (String, ContextValue) -> NonEmptyString -> List String -> List (String, ContextValue)

`with-object`

Adds a nested object to the template context. The object is a list of (key, value) pairs where value is a string.

List (String, ContextValue) -> NonEmptyString -> List (String, String) -> List (String, ContextValue)

`with-objects`

Adds a list of objects to the template context. Each object is a list of (key, value) pairs where value is a string.

List (String, ContextValue) -> NonEmptyString -> List (List (String, String)) -> List (String, ContextValue)

`render`

Renders a template string with the given context.

String -> List (String, ContextValue) -> Result String TemplateError

`render-with-partials`

Renders a template with partials support. partials: A list of (name, template) pairs created with empty-partials/with-partial.

String -> List (String, ContextValue) -> List (String, String) -> Result String TemplateError

`render-with-layout`

Renders a page template within a layout template.

This implements two-phase rendering: 1. First, the page template is rendered, collecting any {{#content-for name}}...{{/content-for}} blocks 2. Then, the layout template is rendered with the page content available as {{{content}}} and collected blocks available via {{yield name}} or {{#yield name}}default{{/yield}}

Example page template: {{#content-for scripts}} <script src="/js/page.js"></script> {{/content-for}} <h1>Page Content</h1>

Example layout template: <html> <head>{{yield styles}}</head> <body> {{{content}}} {{#yield scripts}}<script src="/js/default.js"></script>{{/yield}} </body> </html>

String -> String -> List (String, ContextValue) -> Result String TemplateError

`render-with-layout-and-partials`

Renders a page template within a layout template, with partials support.

String -> String -> List (String, ContextValue) -> List (String, String) -> Result String TemplateError

`render-with-strings`

Renders a template with a simple string map (list of key-value pairs).

String -> List (String, String) -> Result String TemplateError

`context-from-strings`

Creates a context from a list of string pairs.

List (String, String) -> List (String, ContextValue)