laika.config

Configuration for a cover image for e-books (EPUB or PDF).

The optional classifier can be used if the @:select directive is used to produce multiple e-books with slightly different content. The classifier would refer to the name of the configured choice, or in case of multiple choices, to the combination of their names concatenated with -.

Configuration that specify which levels of message severity will cause a transformation to fail and which will be rendered to the output.

Several AST transformation steps can insert nodes with a message into the tree and the way the runtime handles those is configurable.

By default, MessageFilters.defaults will be used which does not render any messages to the output and fails on severity Error or higher. This is usually the best setting for scenarios that do not involve visual debugging.

When running Laika in a preview server (like the one built into Laika's sbt plugin), then MessageFilters.forVisualDebugging will be used internally. This setting will never cause a transformation to fail, but instead render all messages from level Info upwards.

MessageFilters.custom allows the definition of your own combination of filters.

A little abstraction that isolates aspects of parsing and formatting dates from the underlying Date API which may differ between JVM and Scala.js applications.

The design is very minimal as date handling is not a core aspect of Laika. For that reason it uses java.util.Date as the lowest common denominator. Application code should convert it to the most convenient type for the platform in use, e.g. with toInstant on the JVM or with new js.Date(date.getTime().toDouble) in Scala.js.

There was a deliberate choice not to depend on any of the available libraries that port the java.time API to Scala, as this would be to heavyweight, in particular for Scala.js.

Extension specific to site rendering that translates the output path, producing "pretty URLs" that do not contain the html file suffix.

A path like foo/bar.html for example would be translated to foo/bar/index.html so that links can be simply rendered as foo/bar/.

When the render format is anything other than HTML, this extension has no effect.

The extension can be added to a transformer like any other extension:

val transformer = Transformer
 .from(Markdown)
 .to(HTML)
 .using(GitHubFlavor)
 .using(SyntaxHighlighting)
 .using(PrettyURLs)
 .build

or via the laikaExtensions setting when using the sbt plugin:

laikaExtensions += PrettyURLs

Groups configuration for multiple @:select directives.

The @:select directive is a special directive that allows to create alternative versions of the same documentation, for example one with Scala code examples and one with Java. Or as in the case of Laika's own documentation, one showing configuration setup with sbt and the other through the library API.

When using the default Helium theme these alternatives will be rendered as tabs in the website.

While for EPUB and PDF output it triggers the generation of separate books for each of the alternatives and offers them on the download page to cater for the fact that tabs do not work well on paper.

Companion for creating selection config instances that can be passed to Laika configuration and builders that produce configuration of all possible combinations of @:select directives.

See the documentation for the @:select directive in the manual for the full context of this feature.

Extension that registers all code syntax highlighters provided out of the box.

The extension can be added to a transformer like any other extension:

val transformer = Transformer
 .from(Markdown)
 .to(HTML)
 .using(GitHubFlavor)
 .using(SyntaxHighlighting)
 .build

Optional configuration for scanning existing versions that had been generated by a different tool. This setting is optional and serves two purposes:

- If older versions of the documentation had been generated by different tools, Laika can use this configuration for indexing the available paths for "smart linking", which is a feature of the Helium version switcher drop down. The result of the scanning operation will be used to populate the file /laika/versionInfo.json in the output directory.

- If you are using the preview server (either the laikaPreview task in the sbt plugin, or the laika.preview.ServerBuilder from the API) and you want to also test the version switcher drop down menu, then Laika needs to know where older versions are located so that it can serve them, too.

The specified root directory is expected to match the structure of versioned documentation as rendered by Laika. This means that the root directory is expected to have immediate sub-directories with names that correspond to the pathSegment property of the configuration for that version.

Global configuration for versioned documentation.

The order in the Seq properties will be used for any list views in the UI (e.g. for the version chooser dropdown).