Template Engine
Jinja2-compatible template engine for RST report generation
Template Engine
The built-in template engine supports Jinja2-compatible syntax for generating RST documents from data.
For the underlying reStructuredText writing rules and this project's parser support boundaries, see RST Writing Rules.
Basic Usage
import { renderRstTemplate } from '@seqyuan/rst-renderer'
const template = `Report
======
{% for sample in samples %}
{{ sample.name }}
{{ '=' * sample.name.length }}
- ID: {{ sample.id }}
- Status: {{ sample.status|default("pending") }}
{% endfor %}
`
const html = renderRstTemplate(template, {
samples: [
{ name: 'S1', id: '001', status: 'done' },
{ name: 'S2', id: '002' },
],
})Supported Syntax
Variables
{{ variable }}
{{ user.name }}
{{ items["key"] }}Filters
{{ name|default("N/A") }}
{{ items|length }}
{{ text|upper }}
{{ text|lower }}
{{ items|join(", ") }}
{{ obj|tojson }}
{{ value|int }}
{{ value|float }}
{{ value|abs }}
{{ items|first }}
{{ items|last }}
{{ text|trim }}For Loops
{% for item in items %}
{{ loop.index }}. {{ item }}
{% endfor %}Loop variables: loop.index, loop.index0, loop.first, loop.last,
loop.length, loop.revindex, loop.revindex0
Nested Loops
{% for group in groups %}
Group: {{ group.name }}
{% for item in group.items %}
- {{ item }}
{% endfor %}
{% endfor %}If/Else
{% if condition %}
yes
{% else %}
no
{% endif %}
{% if not flag %}
disabled
{% endif %}Comments
{# this is a comment #}Two-Step Rendering
import { renderTemplate, renderRst } from '@seqyuan/rst-renderer'
// Step 1: Template → RST
const rst = renderTemplate(template, context)
// Step 2: RST → HTML
const html = renderRst(rst)Report Template Workflow
For project-level reports, the recommended model is:
- Keep report structure in
report.rst.j2 - Keep project metadata in JSON
- Inject ad hoc values with
-v key=value - Discover repeated result files with
--scan name=glob - Optionally split shared sections with
.. include::plus include expansion
That keeps templates reusable and avoids hardcoding generated file paths such as
upload/plots/WT_Control_umap.png directly into the RST source.
Annopi Compatibility
The template engine is designed to be compatible with annopi-style RST
report templates. Both renderRstTemplate() (one-step) and
renderTemplate() + renderRst() (two-step) workflows are supported.
In practice, the closest matching workflow is:
- RST template as the report skeleton
- external variables from JSON / CLI flags
- wildcard result discovery from the filesystem
- lightweight include reuse for shared fragments