Knap

Knap is a flexible template engine for creating Markdown. It is shared by Obsidian tools, including Web Clipper and Importer.

Knap provides tokenization, parsing, logic, rendering, structured errors, and filters. Applications supply variables and runtime integrations. Knap uses an AST interpreter. It does not use eval or execute arbitrary JavaScript.

The Obsidian Web Clipper documentation includes examples of Knap's shared logic, filters, and variable syntax.

Install

pnpm add knap

Use

import {
	createEngine,
	standardFilters,
	type TemplateVariables,
} from 'knap';

const engine = createEngine({ filters: standardFilters });

const variables: TemplateVariables = {
	title: '  An imported note  ',
	tags: ['reference', 'reading'],
};

const result = await engine.render(
	`# {{ title | trim }}

{% if tags %}Tags: {{ tags | join:", " }}{% endif %}`,
	{ variables },
);

if (result.errors.length === 0) {
	console.log(result.output);
}

Every error contains a stable code, message, line, and column. Use renderOrThrow() when exceptions fit the calling application better:

const output = await engine.renderOrThrow('{{ title | upper }}', { variables });

Filters that deliberately preserve their input after invalid runtime data can report non-fatal diagnostics in result.warnings. Each warning includes a stable code, message, filter, line, and column. Warnings do not make renderOrThrow() throw. Identical warnings from repeated evaluation of the same filter expression are deduplicated within each render.

Syntax

The syntax is inspired by Twig and Liquid.

{{ title }}
{{ title | upper }}
{{ published | date:"YYYY-MM-DD" }}
{{ First name | trim }}

{% if author %}
By {{ author.name }}
{% elseif site %}
From {{ site }}
{% else %}
Unknown source
{% endif %}

{% for item in links %}
- {{ item.title }}: {{ item.url }}
{% endfor %}

{% set heading = title | upper %}

The language supports chained filters, if/elseif/else, for, set, nested properties, array access, comparisons, boolean operators, nullish fallbacks, and whitespace control.

Application variables

Values absent from the variables object can be resolved asynchronously. Knap does not know what a browser tab, vault, selector, schema, or model is.

const result = await engine.render('{{ remoteValue | upper }}', {
	variables: {},
	context: { documentId: 'example' },
	resolveVariable: async (name, { context }) => {
		if (name === 'remoteValue') {
			return loadValue(context.documentId);
		}
		return undefined;
	},
});

Local variables take precedence over the resolver.

Filters

Filters are registered explicitly when an engine is created. The standard registry is available as standardFilters; DOM-dependent filters are available separately from knap/html.

Parameters follow a filter name after a colon, and filters can be chained with |:

{{ title | trim | upper }}
{{ published | date:"YYYY-MM-DD" }}

Standard filters

| Filter | Purpose | | --- | --- | | blockquote | Format text as a Markdown block quote. | | calc | Apply a basic arithmetic operation to a number. | | callout | Format content as an Obsidian callout. | | camel, kebab, pascal, snake | Convert text to the named casing style. | | capitalize, lower, title, upper | Change text capitalization. | | date | Parse and format a date. | | date_modify | Add or subtract a date unit. | | decode_uri | Decode percent-encoded URI text. | | duration | Format ISO 8601 durations or a number of seconds. | | first, last, nth, slice | Select values or ranges from arrays and text. | | footnote | Format values as Markdown footnotes. | | fragment_link | Add text-fragment links using a source URL parameter. | | image | Format a URL as a Markdown image. | | join, split | Join arrays or split strings. | | length | Return the length of a value. | | link, wikilink | Format Markdown links or Obsidian wikilinks. | | list | Format array-like data as a list. | | map | Map fields from structured array data. | | merge | Merge structured values. | | number_format, round | Format or round numeric values. | | object | Select or reshape structured object data. | | remove_attr, strip_attr | Remove selected HTML attributes or all except selected attributes. | | remove_tags, strip_tags | Remove selected HTML tags or all except selected tags. | | replace | Apply one or more text or regular-expression replacements. | | replace_tags | Replace selected HTML tag names. | | reverse, unique | Reverse or deduplicate array-like data. | | safe_name | Sanitize text for use as a file name. | | strip_md, stripmd | Remove Markdown formatting. | | table | Format structured data as a Markdown table. | | template | Apply a small value-substitution template to structured data. | | trim | Remove surrounding whitespace. | | uncamel | Convert camel-cased text into words. | | unescape | Unescape encoded text. | | yaml | Format a value as a YAML-safe scalar. |

Filter metadata, including parameter validation and examples, is exported as standardFilterMetadata. Invalid filter names and invalid parameters are reported by engine.validate() and engine.render().

When a filter cannot use runtime input but preserves that input for compatibility, engine.render() reports a non-fatal structured warning. This includes values such as an unparseable date or an invalid regular expression.

HTML preset

Import htmlFilters from knap/html to enable:

| Filter | Purpose | | --- | --- | | html_to_json | Convert HTML elements into structured JSON values. | | remove_html | Remove selected HTML elements and their contents. |

These filters are opt-in because they require browser-compatible DOM globals such as DOMParser; they do not ship in the root runtime graph:

import { createEngine, standardFilters } from 'knap';
import { htmlFilters } from 'knap/html';

const engine = createEngine({
	filters: {
		...standardFilters,
		...htmlFilters,
	},
});

Custom filters

The engine's filter registry is used for both validation and rendering. Filter parameters use Knap's colon-delimited parameter syntax.

import {
	createEngine,
	standardFilters,
	type TemplateFilter,
} from 'knap';

const markdown: TemplateFilter = (html, param, context) => {
	const baseUrl = param?.replace(/^(['"])(.*)\1$/s, '$2');
	return convertToMarkdown(html, baseUrl, context);
};

markdown.metadata = {
	example: 'markdown:"https://example.com"',
	validateParams: param => ({
		valid: Boolean(param),
		error: 'requires a base URL',
	}),
};

const engine = createEngine({
	filters: {
		...standardFilters,
		markdown,
	},
});

Custom filters may be asynchronous. A filter can also report a non-fatal diagnostic while returning a fallback value:

const lookup: TemplateFilter = async (value, _param, context) => {
	const result = await findValue(value);
	if (result === undefined) {
		context?.reportWarning?.({ message: `Could not find ${value}` });
		return value;
	}
	return result;
};

The filter parameter is passed in its serialized Knap form so filters that accept multiple parameters can preserve delimiters and quoting. A custom filter that expects one scalar parameter can normalize surrounding quotes as above.

Host data needed by a custom filter belongs in the generic engine context:

type HostContext = { sourceUrl: string };

const sourceLink: TemplateFilter<HostContext> = (value, _param, filterContext) => {
	return `[${value}](${filterContext?.context?.sourceUrl})`;
};

const engine = createEngine<HostContext>({
	filters: { ...standardFilters, source_link: sourceLink },
});

await engine.render('{{ title | source_link }}', {
	variables: { title: 'Knap' },
	context: { sourceUrl: 'https://example.com' },
});

API

• createEngine({ filters }) creates an immutable engine-scoped registry.
• engine.render(template, input, options?) returns output, structured errors, and non-fatal warnings.
• engine.renderOrThrow(template, input, options?) returns output or throws TemplateRenderError.
• engine.parse(template) returns the AST and parser diagnostics.
• engine.validate(templateOrAst) validates syntax and the configured filters.
• tokenize(template), parse(template), validateVariables(ast), and validateFilters(ast, metadata) support editor tooling.
• standardFilters contains environment-neutral filters.
• standardFilterMetadata describes the standard registry for standalone validation.
• applyFiltersWithRegistry(value, filterString, registry, context) applies a filter chain when a host needs filter syntax outside a full render.
• htmlFilters is available from knap/html.

Development

pnpm install
pnpm check

Knap is available under the MIT License.