Reference

API

Create an immutable engine-scoped filter registry, then parse, validate, or render templates against application-owned data.

Install

TerminalSHELL

1pnpm add knap

Knap is ESM-first, also ships CommonJS entry points, and requires Node.js 20 or later.

Quick start

render.tsTS

1import {2  createEngine,3  standardFilters,4  type TemplateVariables,5} from 'knap';67const engine = createEngine({ filters: standardFilters });89const variables: TemplateVariables = {10  title: '  An imported note  ',11  tags: ['reference', 'reading'],12};1314const result = await engine.render(15  '# {{ title | trim }}\n\n{{ tags | list }}',16  { variables },17);

Pass an optional generic context when custom filters or resolvers need host data that is not itself a template variable.

Render results

render() always resolves to an output object with structured diagnostics.

Field	Type	Description
`output`	`string`	Rendered Markdown. Empty when parsing fails.
`errors`	`TemplateError[]`	Fatal parser, validation, resolver, or filter errors.
`warnings`	`TemplateWarning[]`	Non-fatal diagnostics reported by filters.

Errors include a stable code, message, line, and column. Warnings also identify the reporting filter and are deduplicated per render.

1if (result.errors.length === 0) {2  console.log(result.output);3}45const output = await engine.renderOrThrow(6  '{{ title | upper }}',7  { variables },8);

Engine methods

createEngine({ filters })

Create an engine with an immutable filter registry.

engine.render(template, input, options?)

Render asynchronously and return output, errors, and warnings.

engine.renderOrThrow(template, input, options?)

Return the output or throw TemplateRenderError.

engine.parse(template)

Return the AST and parser diagnostics.

engine.validate(templateOrAst)

Validate syntax and filter names or parameters.

Set { trimOutput: false } in render options to preserve surrounding template whitespace.

Editor tooling

The lower-level exports let editors tokenize once, inspect an AST, and validate variables or filters independently.

validate.tsTS

1import {2  parse,3  standardFilterMetadata,4  validateFilters,5  validateVariables,6} from 'knap';78const parsed = parse(template);9const filterErrors = validateFilters(parsed.ast, standardFilterMetadata);10const variableNames = validateVariables(parsed.ast);

applyFiltersWithRegistry() applies a synchronous filter chain when a host needs Knap filter syntax outside a full render.

Package exports

Import	Includes
`knap`	Engine, parser, tokenizer, standard filters, diagnostics, and public types.
`knap/html`	DOM-dependent `html_to_json` and `remove_html` filters.