obsidian/templater

The slice of Templater’s INTERNAL API this library talks to, and the runtime narrowing that gets hold of it.

Templater publishes no API. Rendering a template against a file and getting the resulting string back is only reachable through undocumented internals hanging off app.plugins.getPlugin('templater-obsidian').templater — create_running_config, functions_generator.generate_object, read_and_parse_template, and a RunMode enum. Every plugin that wants it re-derives the same reverse engineering, which is why it lives here instead.

This module is explicitly BEST-EFFORT. Nothing it binds to is documented or covered by Templater’s semantic versioning, so a Templater release may rename or reshape any of it without warning. The shapes below were read from Templater 2.24.3. Two deliberate consequences follow:

• resolveTemplaterApi returns null — a Templater too old, too new or too broken to talk to reads as “not there” and the integration stays dormant. - requireTemplaterApi throws a TemplaterUnavailableError that NAMES the plugin and the reason, rather than letting a Cannot read properties of undefined surface from somewhere inside Templater.

The types are DECLARED HERE rather than imported, and narrowed to the members actually called: Templater ships no npm types package, and depending on it would turn an optional integration into a build-time dependency (see rule L9).

The second thing this module supplies is an active-file answer. While a template renders, app.workspace.getActiveFile() still points at whatever the user happens to have open — NOT at the file the template is being rendered for — so a plugin’s own helper called from inside a template resolves links against the wrong note. TemplaterActiveFileProvider answers with the render target for the duration of a parseTemplate call and falls back to the workspace otherwise. Note this is about the CONSUMER’s helpers: Templater’s own tp.file.* already resolves through the running config’s target_file and needs no help.

Classes

Class	Description
TemplaterActiveFileProvider	Active-file provider that answers with the file a parseTemplate render is currently for, falling back to the workspace’s active file when no render is in flight. This is the piece that makes a consumer’s own template helpers resolve against the right note: during a render the workspace still has whatever the user was looking at open, which is rarely the target.
TemplaterUnavailableError	Thrown when Templater’s internal API cannot be handed over, carrying the TemplaterUnavailabilityReason that says why.

Interfaces

Interface	Description
GetTemplaterFunctionsParams	Parameters for getTemplaterFunctions.
ParseTemplateParams	Parameters for parseTemplate.
TemplaterApi	Templater’s internal API object, narrowed to the members this library calls. Its members are snake_case because Templater’s are; they are transcribed rather than renamed so the shape can be checked against Templater’s source at a glance.
TemplaterFunctionsGenerator	The functions_generator half of TemplaterApi.
TemplaterRunningConfig	One Templater render, as Templater’s create_running_config describes it. Its members are snake_case because Templater’s are.

Functions

Function	Description
getTemplaterFunctions	Gets Templater’s functions object — the tp a template is evaluated against — so a caller can invoke tp.date.now(), tp.file.title and the rest outside a template.
getTemplaterRenderTargetFile	Gets the file the innermost in-flight parseTemplate render is for. Renders nest — a template may render another — so the calls form a stack and this reports the top of it. Outside any render it is null.
parseTemplate	Renders a Templater template against a target file and returns the resulting text, without writing anything. For the duration of the call getTemplaterRenderTargetFile and TemplaterActiveFileProvider report targetPathOrFile, so a consumer’s own helpers invoked from inside the template resolve against it rather than against whatever the user has open.
requireTemplaterApi	Gets Templater’s internal API, throwing when it cannot be had. Use this where the caller cannot carry on without Templater — the error names the plugin and says which of the two failures occurred. Use resolveTemplaterApi instead where the integration is optional.
resolveTemplaterApi	Gets Templater’s internal API, when Templater is installed, enabled and still the shape this library expects.

Enums

Enum	Description
TemplaterRunMode	Templater’s RunMode enum, which says what kind of render a TemplaterRunningConfig describes. The numeric values ARE Templater’s, and the members are listed in its declaration order so the two can be compared line for line. They are written out explicitly all the same, because they cross into Templater as integers — never renumber them.
TemplaterUnavailabilityReason	Why Templater’s internal API could not be handed over.

Variables

Variable	Description
TEMPLATER_PLUGIN_ID	Templater’s plugin id, as its manifest declares it.