Templates

A template is a Git repository that packages one kind of conversion: a tern.toml manifest declaring profiles and pipelines, the Lua converters they use, and data files such as filters, stylesheets or setup scripts. Projects list templates in .tern/config.toml, and tern -u installs them. Reference https://git.yhkze.net/tern/pandoc-template for a complete one.

Configuration

Each [[templates]] entry in .tern/config.toml installs one template:

[[templates]]
name = "pandoc-template"
url = "https://git.yhkze.net/tern/pandoc-template.git"
ref = "v1.0"        # optional: tag, branch or commit

The name decides where the template is installed (.tern/converters/<name>/, .tern/data/<name>/) and how its profiles and pipelines are addressed (<name>/<profile>). Installing one template several times under different names gives independent configurations of the same upstream, e.g. one install for docs/ and another for the top-level README.

Commands

Install or update every configured template:

tern -u

tern -u fetches each template, copies its converters and data, and recomputes its profiles from the manifest plus the overrides below; pipelines are replaced entirely. Conversion history is kept, so an update does not force a full rebuild. Because the result depends only on the manifest and .tern/config.toml, rerunning it reproduces the same state.

tern -a installs from the cache without fetching, and skips profiles that already exist.

Template directory Installed to
converters/ .tern/converters/<name>/
data/ .tern/data/<name>/
tern.toml profiles Database, as <name>/<profile> with engine <name>/<file>.lua
tern.toml pipelines Database, as <name>/<pipeline>

tern -u replaces .tern/data/<name>/, so edits to installed copies are lost on the next update. Durable changes belong in a fork of the template; profile and pipeline changes belong in .tern/config.toml.

Overrides

Profiles and pipelines are derived on every tern -a and tern -u, so a value edited in the database (through the TUI or directly) is recomputed away. Project-specific adjustments live in .tern/config.toml.

Profiles

[templates.overrides.<profile>] replaces fields of a profile, keyed by its short name in the template’s tern.toml:

[[templates]]
name = "pandoc/readme"
url = "https://git.yhkze.net/tern/pandoc-template.git"

[templates.overrides.pandoc]
source_root = "."
ignore_patterns = ["*", "!README.md"]

The overridable fields are source_root, source_file_extension, output_root, output_file_extension, options and ignore_patterns; omitted ones keep the manifest’s value. engine is not overridable, since it names a converter the template ships.

Snippets

Stage snippets are shell commands that profile overrides cannot reach. [templates.snippet_overrides] replaces them, keyed by "<pipeline>/<stage>". A template that refers to its own default install path needs this under any other name:

[templates.snippet_overrides]
"convert/convert" = ["sh .tern/data/pandoc/readme/setup.sh"]

An empty list removes the stage’s snippets.

A key naming a profile or stage the template does not declare is an error, as is an unknown field inside an override block, so typos and upstream renames surface immediately.

Concurrent snippets

Pipelines run in parallel, and so do the items within a stage (reference Pipelines). Two installs of one template therefore run their snippets at the same time, against the same output root if they share one, and a snippet that writes files there must assume another copy of itself writes the same paths simultaneously.

A check-then-copy races on a cold output directory:

[ -f "$dst" ] || cp "$src" "$dst"

Both processes find the destination missing, both have cp create it with O_CREAT|O_EXCL, and the loser aborts with cannot create regular file: File exists. It passes every warm rebuild and fails in CI. cp -f does not help: it only unlinks and retries when the destination cannot be opened. Writing to a temporary file in the destination directory and mv-ing it into place is safe: rename(2) is atomic and replaces the target, so concurrent writers end in last-writer-wins and no reader sees a half-written file.

Cache

Each template is cloned to .tern/cache/<name>/, and the installed converters and data are copies taken from it. The cache ignores itself through a generated .tern/cache/.gitignore.

The cache is keyed by name, not URL, so two installs of one upstream get two independent clones. Changing a template’s url re-points the existing clone’s origin on the next tern -a or tern -u, keeping the objects already downloaded; a URL with unrelated history converges too, since the fetch prunes and the worktree is reset to the configured ref.

Writing a template

A template repository holds:

The manifest declares the template’s profiles and the pipelines that run them:

name = "my-template"

[[profiles]]
name = "default"
engine = "pandoc.lua"
source_root = "docs"
source_file_extension = "md"
output_root = "docs-html"
output_file_extension = "html"
options = ["--standalone --toc"]
ignore_patterns = ["drafts/"]

[[pipelines]]
name = "build"

[[pipelines.stages]]
name = "convert"
converters = ["default"]
snippets = ["sh .tern/data/my-template/setup.sh"]

Paths in options and snippets use the default install name (.tern/data/my-template/); projects that install the template under another name retarget them with overrides.