sbt Plugin

The core of the Laika toolkit does not depend on sbt in any way. The sbt plugin merely provides a thin layer on top of the library API, exposing Laika's feature set as sbt tasks and settings.

This chapter only covers the topics which are specific to using Laika with sbt, while most other parts of the manual apply to both use cases, library and plugin.

Adding the Plugin to the Build

Laika's sbt plugin requires sbt 1.x.

If you still need to use sbt 0.13.x, you can use Laika 0.7.0 which was the last release supporting that sbt version.

First add the plugin to project/plugins.sbt:

addSbtPlugin("org.planet42" % "laika-sbt" % "0.17.1")

Then enable the plugin in your project's build.sbt:


Preparing Content

The plugin expects the source files in the src/docs directory inside your project. This default can be overridden with:

Laika / sourceDirectories := Seq(target.value / "somewhere-else")

You can provide multiple input directories which will be merged into Laika's Virtual Tree Abstraction.

Laika does not have any special directories and content can be nested in sub-directories down to arbitrary levels. For more details on how to organize content, see Directory Structure.

The plugin distinguishes between the following file types:

Generating a Site

For parsing your markup files and generating a site simply run:


This will parse all files with the extensions .md, .markdown or .rst and render them as .html files in the same directory structure as the input.

It will also copy all other file types over to the target folder (apart from templates and laika configuration files).

The site will be generated in the directory target/docs/site within your project. The default can be changed with:

laikaSite / target := target.value / "somewhere-else"

Laika builds on sbt's caching features, therefore if neither any input files have been modified nor any output files removed, it is a no-op.

Including EPUB and PDF

EPUB and/or PDF files can be included with these settings:

laikaIncludeEPUB := true
laikaIncludePDF  := true

In this case the laikaSite task will generate EPUB and/or PDF files in the root directory of your output, in addition to the generated HTML site. The name of the files will be <project-name>-<version>.<epub|pdf> by default. You can change it with:

laikaEPUB / artifactPath  := target.value / "my-docs.epub"
laikaPDF / artifactPath   := target.value / "my-docs.pdf"

For other e-book configuration options like navigation structures and cover images see E-Books (EPUB & PDF).

Including Scaladoc

The following setting causes the scaladoc output of your project to be included in the generated site:

laikaIncludeAPI := true

It will be copied into the api directory of your site's target, unless you change its setting:

laikaCopyAPI / target := (laikaSite / target).value / "somewhere-else"

Generating Individual Formats

Instead of using the laikaSite task, you can also selectively pick the output formats to generate on each run with the laikaGenerate task:

laikaGenerate html epub pdf

This will parse all files with the extensions .md, .markdown or .rst and render them in the specified list of formats. It is efficient in that the parsing of markup files only happens once to obtain a document AST and use this structure to render all formats.

Valid format arguments are html, epub, pdf, xslfo, ast. The latter is a debug output that renders the document AST in a formatted structure.

Finally if you only work with a single format there are also shortcut tasks for those: laikaHTML, laikaEPUB, laikaPDF and laikaAST.

Plugin Settings

The remaining configuration options are not specific to the plugin use case and merely mirror the features of the library API, apart from differences in the syntax/mechanics which with they are applied, which are reflected in the corresponding code examples. For this reason this section only gives a very brief overview while linking to the relevant sections in the other chapters.

laikaTheme Setting

This setting allows to configure the built-in Helium theme or a 3rd-party theme you might use. You can also use it to specify an empty theme if you want to put all templates and styles right into your input directory.

Example for applying a few Helium settings:

laikaTheme := Helium.defaults
    title = Some("Project Name"),
    language = Some("de"),

Setting an empty theme:

laikaTheme := Theme.empty

If you do not use this property Laika will run with the default settings of the Helium theme, meaning your site and e-books will look exactly like this documentation, including all color and font choices.

Since the theme offers a lot of configuration options it has its own dedicated chapter Theme Settings.

To just give a brief overview, those settings allow you to configure:

laikaConfig Setting

A builder-style API for basic configuration options grouped in a single sbt setting. These are configuration options not tied to the default theme and are available even when using a 3rd party theme or no theme at all.


laikaConfig := LaikaConfig.defaults.strict.withRawContent

laikaExtensions Setting

Register implementations of the ExtensionBundle API, either provided by the library or extensions you created yourself.


laikaExtensions := Seq(GitHubFlavor, SyntaxHighlighting)

Configuring Input and Output

Most of these setting are introduced in the sections above.

Freely Composing Inputs

If you need additional flexibility instead of just configuring one or more input directories, e.g. when there is a need to generate content on-the-fly before starting the transformation, you can use the laikaInputs setting. This setting completely overrides any value set with Laika / sourceDirectories.

val inputs = InputTree[F]
  .addDirectory("/path-to-my/images", Root / "images")
  .addClasspathResource("my-templates/default.template.html", DefaultTemplatePath.forHTML)
  .addString(generateStyles(), Root / "css" / "site.css")

In the example above we specify two directories, a classpath resource and a string containing CSS generated on the fly. By default directories get merged into a single virtual root, but in the example we declare a mount point for the second directory, which causes the content of that directory to be assigned the corresponding logical path.

Always keep in mind that declaring inputs and outputs are the only places in the Laika universe where you'd ever use concrete file system paths. Beyond this configuration step you are entirely within Laika's virtual path abstraction and refer to other resources by their virtual path. This is true for linking, using image resources, specifying templates to use in configuration headers, and so on. It means that everything you can refer to in your markup files needs to be included in the input composition step.

The InputTreeBuilder API gives you the following options:

When generating input on the fly it is usually a question of convenience or reducing boilerplate whether you choose to generate a string for parsing or the AST directly.

For the complete API see InputTreeBuilder.

Settings for the laikaSite task

Finally there are three boolean flags that only affect the laikaSite task.

Inspecting Laika's Configuration

Run show laikaDescribe to get a formatted summary of the active configuration, installed extension bundles and lists of input and output files.


Extension Bundles:
  Laika's Default Extensions (supplied by library)
  Laika's directive support (supplied by library)
  Laika's built-in directives (supplied by library)
  Default Syntax Highlighters for Code (supplied by library)
  Document Type Matcher for Markdown (supplied by parser)
  Default extensions for reStructuredText (supplied by parser)
  Support for user-defined reStructuredText directives (supplied by parser)
  Standard directives for reStructuredText (supplied by parser)
  Document Type Matcher for reStructuredText (supplied by parser)
  Strict Mode: false
  Accept Raw Content: false
  Render Formatted: true
  Markup File(s)
    File '/dev/project/src/'
    File '/dev/project/src/'
    In-memory string or stream
  Configuration Files(s)
  CSS for PDF
  Copied File(s)
    File '/dev/project/src/main.css'
  Root Directories
  Directory '/dev/project/target/docs'""""