The core of the Laika toolkit does not depend on sbt in any way, and therefore comes with a plugin that provides the glue necessary to expose 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 embedded use and sbt plugin.

Adding the Plugin to the Build

Laika's sbt plugin requires sbt 0.13.x.

First add the plugin to project/plugins.sbt:

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

If you want to install it globally, add the line above to ~/.sbt/1.0/plugins/build.sbt instead.

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


You can now add content to the directory src/docs inside your project and run laikaSite from within sbt to generate the site in target/docs/site. See the following sections for details.

Editing Content

Laika expects the site content to be organized in a directory. By default this is src/docs. In contrast to several similar tools content in Laika is hierarchical. Subdirectories can contain markup files, too, and the hierarchy can get visualized in a table of contents. Furthermore you can also specify additional directories to be merged into the main directory, which allows to keep reusable templates and styles (other tools would call it "themes") in a separate place.

The directories can contain different types of files:

  • All of the supported text markup formats (currently this is Markdown and reStructuredText). The default parser of the plugin allows to use both formats in the same document tree (including cross linking between the two formats) and recognizes them by the file suffix (.md or .markdown for Markdown and .rst for reStructuredText).

  • A configuration file directory.conf which allows to specify the document order for navigation, the directory title, autonumbering options and other settings.

  • A template file default.template.<format> that gets applied to all markup files in this directory (and its subdirectories unless overridden). The suffix may be any output format in Laika that supports templating, currently this is .html for HTML output and .fo for PDF or XSL-FO output. A very basic HTML template may look like this:

        <div class="content">

    The two placeholders enclosed in double curly braces will be replaced with the title and content of the parsed markup document.

  • Other static files that simply get copied to the target directory.

For more details on the template engine, see the chapter Templates.

For features like titles, sections, cross-linking, auto-numbering, document order and tables of content, see the chapter Document Structure.

For details about Markdown and reStructuredText see the chapter Supported Markup.

For details about rendering see the chapter Supported Output Formats.

Laika Tasks for sbt

Laika currently supports the following sbt tasks:

  • laikaSite Processes all files from the source directories and renders the result to target/docs/site (unless overridden). By default only HTML output gets rendered by this task. You can add API documentation for a Scala project with the includeAPI setting and a PDF file rendered from the same markup sources with the includePDF setting.

  • laikaPackageSite
    Packages the site into a zip file inside the target/docs directory. Depends on the laikaSite task.

  • laika:clean
    Deletes the contents of Laika's target directory only. Alternatively you can also run the global clean task which will delete content generated by Laika together with the target directories of other tasks.

  • laikaGenerate Generates the output format specified as arguments to this task. For example laikaGenerate html pdf generates an HTML site as well as a PDF file from the parsed source markup. The markup will only get parsed once, therefore this task is very efficient for producing multiple output formats. The formats supported as arguments to this task are html, pdf, xslfo and ast. If you only want to generate one output format there are shortcut tasks for each of them: (laikaHTML, laikaPDF, laikaXSLFO, laikaAST)

A future version of the plugin will add support for epub (scheduled for the 0.10 release).

The default settings for these tasks should be sufficient for many use cases. The following sections show how you can override the defaults.

Basic Settings

The following list shows the names, types and default values of the basic settings:

  • sourceDirectories in Laika - Seq[File] - default Seq("src/docs")
    Specifies one or more source directories to process. All specified directories can contain any of the supported file types and will get merged into a tree with a single root.

  • target in Laika - File - default target/docs
    Specifies the directory where the plugin should generate the site. This key also has separate values scoped to the individual tasks: target in laikaSite (default target/docs/site), target in laikaCopyAPI (default target/docs/site/api) and target in laikaPackageSite (default target/docs).

  • excludeFilter in Laika - FileFilter - default HiddenFileFilter
    Specifies files to exclude from processing. Note that Laika ignores any includeFilter you set, as the tool needs more than a simple yes/no decision for deciding how to process files. If a simple exclusion filter is not sufficient, you can specify a laikaDocTypeMatcher as explained in Settings for Customization Hooks.

  • laikaExtensions - Seq[ExtensionBundle] - default Nil The main extension hook that allows to add one or more ExtensionBundle instances for adding directives, parser extensions, rewrite rules or custom renderers. See the sections below for examples for custom renderers and rewrite rules.

  • laikaConfig - LaikaConfig allows to specify additional flags and settings through instances of LaikaConfig:

    • encoding: specifies the character encoding (default UTF-8)
    • strict: switches off all extensions and only uses features defined in the spec of the markup languages (default false)
    • rawContent: allows to include raw content like HTML embedded in text markup (default false)
    • renderMessageLevel: the minimum level required for an invalid node to be rendered to the output (default Warning)
    • logMessageLevel: the minimum level required for an invalid node to be logged to the console (default Warning)
    • parallel: whether parsing and rendering should happen in parallel (default true)
  • laikaIncludeAPI - Boolean - default false
    Indicates whether generated scaladoc APIs should be included when running the laikaSite task. The folder for the API can be set with target in copyAPI (default target/docs/site/api).

  • laikaIncludePDF - Boolean - default false Indicates whether a generated PDF file should be included when running the laikaSite task. The file name for the PDF can be set with artifact in pdf (default target/docs/site/<noduleName>-<version>.pdf).

Settings for Customization Hooks

Laika allows to easily add custom logic to the processing of documents. When all you need to adjust is the processing of one or more particular nodes types, a simple partial function allows to do that while still benefiting from the defaults for all other node types.

When working with the document tree (the internal AST representing the document structure), it is most comfortable to add the following import to the build:

import laika.ast._

Custom Renderers

A custom renderer allows to override the generated output for one or more specific node types, while falling back to the default renderers for all other node types.

The laikaHtmlRenderer shortcut allows to add a custom HTML renderer to the laikaExtensions setting and expects a function of type HTMLWriter => RenderFunction where RenderFunction is a type alias for PartialFunction[Element, Unit]. Element is the base trait for all nodes in a document tree. For all elements where this partial function is not defined, Laika will use the default renderers for all node types.

The following simple example shows how you can add a style to the renderer for the <em> tag:

laikaExtensions += laikaHtmlRenderer { out => {
  case Emphasized(content, _) => 
      out << """<em class="big">""" << content << "</em>" 

For more details see the chapter Customizing Renderers.

Similarly the laikaFoRenderer shortcut can be used to add a custom XSL-FO renderer of type FOWriter => RenderFunction. XSL-FO is an interim format for PDF output, so this option would also allow to change the appearance of PDF documents.

Custom Rewrite Rules

When customizing renderers you have to repeat the step for each output format like HTML or PDF (and a subsequent version will add support for epub). A rewrite rule lets you express a transformation of a node inside the document tree before rendering, so it would have an effect on all output formats.

A rewrite rule is a function of type PartialFunction[Element, Option[Element]]. If the function is not defined for a particular element the old element is kept in the tree. If it returns Some(Element) this element replaces the old one. If the function returns None the old element is removed from the tree.

The following (somewhat contrived, but simple) example shows how to turn each Emphasized node into a Strong node:

laikaExtensions += laikaRewriteRule { 
  case Emphasized(content, opts) => Some(Strong(content, opts))

For more details see the chapter Document Tree Rewriting.

Custom Document Type Matcher

A document type matcher categorizes an input document based on its path. It is a function that takes a Path instance (from the Laika API, not sbt.Path) and returns the matching DocumentType with valid values being one of the following objects:

Markup, Template, Dynamic, Static, Config, Ignored

These values correspond to the descriptions provided in Document Types.

The function is of type Path => DocumentType and can be added to the laikaExtensions setting:

laikaExtensions += laikaDocTypeMatcher {
  case path: Path => match {
    case "" => Markup
    case "hello.js" => Static

Settings for Directives

Directives are Laika's extension hook for both, templates and text markup. They allow to add new tag-like constructs without touching the existing parsers.

Laika supports two flavors of directives, one compatible with the reStructuredText specification and the other with a Laika-specific syntax.

The reStructuredText variant is supported for full compatibility with the reStructuredText specification and reuse of existing reStructuredText files making use of some of the standard directives. Laika supports almost all of the directives defined in the specification. Add an instance of type RstExtensionRegistry to the laikaExtensions setting for adding custom implementations to the built-in ones. For more details on this directive type see Extending reStructuredText.

The Laika variant is more flexible, as it can be used in template files as well as Markdown and reStructuredText markup. It is also somewhat simpler in syntax and configuration while offering the same functionality. It comes with a small set of predefined directives in this syntax. Add an instance of type DirectiveRegistry to the laikaExtensions setting for adding custom implementations to the built-in ones. For more details on this directive type see Directives.

The examples in the two chapters linked above show how to implement a directive and register it either for use in sbt or in embedded mode.

Using Laika for GitHub Pages

If you want to generate the site and push it up to the gh-pages branch of your GitHub repository in one go, you can combine Laika and the sbt-ghpages plugin.

Add the sbt-ghpages plugin to project/plugins.sbt:

resolvers += "jgit-repo" at ""

addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.5.2")

Configure the plugins in build.sbt:

enablePlugins(LaikaPluging, GhpagesPlugin)

git.remoteRepo := "{your username}/{your project}.git"

git.gitCurrentBranch := "master"

mappings in synchLocal := (mappings in laikaSite).value

It is the last line that connects the two plugins, but there is no need to understand how that line works.

Finally run the task ghpages-push-site. This will also trigger the Laika transformation if the site output is not up-to-date.