Mastering Texkit's Template Syntax: A Complete Guide

Why Template Syntax Matters

In a well-structured documentation stack, the template layer handles the heavy lifting of presentation logic. A poorly defined template syntax can lead to fragile pipelines that break when edge cases arise. Texkit prioritizes readability and type safety, allowing developers to write templates that act as self-documenting code.

Whether you are rendering a simple API reference or a complex multi-page report, mastering these core constructs is essential for building scalable document generation workflows.

The most fundamental operation in any templating language is variable injection. Texkit uses double curly braces {{ }} to access data from your context.

By default, values are injected as HTML-escaped strings. For raw HTML, use triple braces {{{ }}}}.

Basic Injection

Assuming a context object user with properties name and role:

<h1>Hello, {{ user.name }}</h1>
<p>Role: {{ user.role }}</p>

Tip: Always provide a fallback value using the pipe operator | default to prevent runtime errors on missing keys.

<p>Status: {{ user.status | default('Active') }}</p>

Texkit supports standard conditional blocks to control flow based on data evaluation. The syntax mirrors control structures found in modern programming languages.

Truthy and Falsy Rules

Values are evaluated as true if they are non-empty strings, non-zero numbers, or truthy booleans. The value null, undefined, and empty arrays/objects are considered falsey.

{% if product.stock > 0 %}
  <button class="btn btn--primary">Add to Cart</button>
{% else %}
  <button class="btn btn--outline" disabled>Out of Stock</button>
{% endif %}

Loops in Texkit are designed for iterating over arrays (lists) and dictionaries (objects). The loop context provides access to index, first, and last properties.

{% for item in apiResponse.items %}
  <li>{{ item.id }}: {{ item.title }}{% if item.last %}</li>{% else %}, {% endif %}{% endfor %}

You can also iterate over object keys:

{% for key, value in config %}
  <!-- {{ key }} is set to {{ value }} -->
{% endfor %}

Filters modify the output of variables before they are rendered. They are applied using the pipe character | and can be chained.

• String: | uppercase, | truncate(20)
• Date: | format('iso'), | date('long')
• Number: | round, | currency('USD')

Example:

<p>Published: {{ article.date | date('medium') }}</p>
<p>Summary: {{ article.excerpt | truncate(100, '...') }}</p>

To avoid code duplication, break your templates into reusable components using Partials. Partials are stored in a partials/ directory.

Includes

Includes load and render a template at the current location. They do not return data, they just insert it.

{% include 'partials/header.txk' %}

Partials

Partials are functions that return a string. This is useful for generating repeated UI elements or complex blocks that need to be reused multiple times within a single file.

{% set user_card = partial('components/user-card.txk', { user: current_user }) %}
{{ user_card }}

Texkit automatically escapes HTML tags to prevent injection attacks. However, when you need to render raw HTML or JavaScript, you need to disable escaping temporarily.

Manual Escaping

<code><!-- Use the raw filter -->
{{ my_html_string | raw }}
</code>

Raw Blocks

For larger blocks of code that should not be parsed by Texkit, use the {% raw %} tag.

{% raw %}
  <div class="literal-html">{{ this will not parse }}</div>
{% endraw %}