Substitution Variables

Substitution Variables can used in text markup documents and in templates for any output format.


The syntax is part of Laika's HOCON support and matches the HOCON spec.

A mandatory reference can be inserted with the key of the variable enclosed between ${ and }:


If such a value is undefined, the transformation will fail (unless you tweaked the configuration for Error Handling).

An optional reference can be expressed by adding an additional ? right before the variable key:


If an optional reference points to an undefined value, the reference in the template is substituted with an empty string.

Pre-Defined Values

Laika provides a set of pre-defined variables in three namespaces. One is the cursor namespace that holds information about the current document and its siblings and parents. The second is laika holding all values coming from Laika's internal configuration. Finally the helium namespace which is only populated if you use Laika's default theme called Helium, contains the theme configuration and some pre-built AST nodes.

Cursor Values

Values from the cursor namespace expose information about the current document and its siblings and parents. They can be used in templates or markup documents to create links or insert content. If you need to create complex navigation structures though, it is usually best to prefer Implementing Directives over complex template logic.

Internal processing in Laika is not stringly, but based on traversing and modifying ASTs. Therefore, if a substitution variable listed below is described as holding an AST, the node in the AST representing the variable will be replaced by this referenced AST. Rendering of the AST happens later as a final step in the processing pipeline.

This is a complete list of values exposed in the cursor namespace:

Laika Configuration Values

These are usually not accessed in user templates and mostly intended for Laika's own internal processing, but are nevertheless exposed like any other value in the configuration.

User-Defined Values

In addition to the library's pre-defined values users can define their own values in any scope.

The only reserved namespaces for variable keys are cursor (e.g. cursor.currentDocument.title), laika (e.g. laika.pdf.coverImage) and helium for the default theme. You can freely choose any key outside of these three namespaces.

Programmatic Definition

You can add arbitrary configuration values when building a Parser, Renderer or Transformer:

laikaConfig := LaikaConfig.defaults
  .withConfigValue("project.version", "2.4.6")
val transformer = Transformer
  .withConfigValue("project.version", "2.4.6")

You can refer to these values in templates and text markup:

The latest stable release is ${project.version}.

Values declared in a builder instance are available globally, but can be overridden by HOCON definitions in narrower scopes, as shown in the next section.

HOCON Definition

Programmatic configuration is recommended over file-based HOCON configuration wherever possible, but if you need to associate values with a particular directory, text markup document or template, instead of declaring them globally, you can define them in the corresponding locations:

Just be aware that these values are then not available globally, but only in the corresponding scope they were defined in.

Example for defining a variable in a configuration header in a text markup document:

  project.version = 2.0.2

Document markup here...

This value can then be accessed within that document or inside a template applied to that document with the usual syntax:

The latest stable release is ${project.version}.

Programmatic Access

The same variables that you can access with HOCON-style substitution references in templates and markup files, are also available programmatically if you are working with a document tree. The DocumentCursor, DocumentTree, Document and TemplateDocument types all have a config property that exposes those values:

val doc: Document = ???
val version: Either[ConfigError, String] = 

See Config for details about the Config API.