Laika is a customizable and extensible toolkit for transforming lightweight text markup and template based site generation.

It has been designed for two primary usage scenarios:

  • Embedded use (e.g. web applications that allow user input in one of the supported markup syntaxes)

  • As a standalone tool (e.g. using Laika's sbt plugin to produce the project's documentation)

Laika does not require the installation of any external tools.

It is Open Source under the Apache 2.0 License.

If you wonder about the name of the project and have never heard about Laika, you can read about her here.

Getting Started

The current version is published to Maven Central for Scala 2.10 and 2.11.

The sbt plugin is published to the sbt plugin repository for sbt 0.13.x.

Using the sbt Plugin

Add the plugin to project/plugins.sbt:

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

Import its default settings in your project's build.sbt:

LaikaPlugin.defaults

Add Markdown, reStructuredText or HTML template files to src/docs in your project and run the laika:site task from within sbt to generate the site in target/docs/site.

Using Laika Embedded

Adding the Laika dependency to your sbt build:

libraryDependencies += "org.planet42" %% "laika-core" % "0.6.0"

Example for transforming from file to file:

Transform from Markdown to HTML fromFile "hello.md" toFile "hello.html"

Example for transforming an entire directory of markup files:

Transform from ReStructuredText to 
  HTML fromDirectory "source" toDirectory "target"

Example for transforming an entire directory of markup files to a single PDF file:

Transform from Markdown to PDF fromDirectory "src" toFile "hello.pdf"

When using Laika's PDF support you need to add another dependency to your build:

libraryDependencies += "org.planet42" %% "laika-pdf" % "0.6.0"

Other Resources

There will also be a dedicated forum in case of growing interest in Laika.

This manual is written in Markdown and transformed by Laika. Its source is included in the repository inside the docs folder.

Features

  • Support for Markdown and reStructuredText as input

  • Support for HTML, PDF, XSL-FO and PrettyPrint (for debugging) as output

  • Template-based Site Generation

  • Support for tables of contents, convenient cross-linking between documents and auto-numbering of documents and sections for all supported markup formats

  • Support for styling of PDF documents with CSS

  • sbt plugin, exposing all Laika features and customization hooks as sbt settings and tasks

  • Custom Directives (tags) for templates and text markup, with type-safe and concise DSL for their declaration

  • Customization hooks for renderers (based on simple partial functions that change the output for specific node types)

  • Document Tree Rewriting (hooks for modifying the document AST, consisting of case classes, between parsing and rendering, based on simple partial functions)

  • Simple contracts and APIs for adding new parsers and renderers

  • A set of generic and fast parser combinators for common tasks in markup parsing that are not based on the commonly used (and often slow) regex parsers

  • Various options for input and output (strings, files, java.io.Reader/Writer, java.io streams)

  • Parallel processing of parsers and renderers

  • More than 1,000 tests

Road Map

  • New renderer for epub (0.7)

  • Integrated support for syntax highlighting in source code (0.8)

  • Various Markdown extensions: GitHub Markdown, MultiMarkdown, CommonMark, YAML headers, etc. (0.9)

  • API polishing (1.0)

After these four releases priorities depend on user demand, therefore no decision has been made yet for these other ideas:

  • Markup syntax as output format

  • Java API / Gradle plugin

  • A command line interface

Release History

  • 0.6.0 (May 23, 2016):

    • Support for rendering PDF documents
    • Support for rendering XSL-FO output
    • New CSS parser supporting a large subset of standard CSS
    • Support styling of PDF documents with CSS
    • Support for different templates per output format
    • New sbt tasks: html, pdf, xslfo, prettyPrint for rendering a single output format
    • New sbt task generate for rendering one or more output formats (e.g. laika:generate html pdf)
    • Integrate PDF output into existing sbt task laika:site via new setting includePDF
    • New directives pageBreak, style and format
    • Changes to the Render and Transform API to allow for the merging of an entire directory of input files into a single output file (as required by PDF rendering)
  • 0.5.1 (Oct 10, 2015):

    • Cross-compile for Scala 2.11 and 2.10
    • Publish the sbt plugin to the new plugin repository on Bintray
    • Upgrade to ScalaTest 2.2.4
  • 0.5.0 (Jan 9, 2014):

    • New sbt plugin, exposing all Laika features and customization hooks as sbt tasks and settings
    • New option to merge multiple input directories into a tree structure with a single root, allowing to keep reusable styles or templates ("themes") separately
    • New option to use Markdown and reStructuredText markup in the same input tree, including cross-linking between the two formats
    • Move to a multi-project build and rename the main artifact from laika to laika-core
    • Upgrade to ScalaTest 2.0 and sbt 0.13
    • Drop support for Scala 2.9.x
  • 0.4.0 (Nov 22, 2013):

    • Template-based site generation
    • Support for tables of contents, convenient cross-linking between documents and autonumbering of documents and sections for all supported markup formats
    • Custom Directives for templates and text markup
    • Document Fragments that can be rendered separately from the main document content
    • New API for batch processing for parse, render or full transform operations
    • Parallel processing of parsers and renderers
  • 0.3.0 (Aug 3, 2013):

    • Support for most of the standard directives and text roles of the reStructuredText reference parser (admonitions, figure, image, code, raw and many more)
    • Now integrates the official Markdown test suite (and many fixes to make it pass)
    • Now integrates a test for transforming the full reStructuredText specification (which, of course, is written in reStructuredText) and many fixes to make it pass
    • Adds the renderer option HTML.unformatted for terse output without indentation or whitespace (often desirable when writing the rendered document to a database for example)
    • Adds a new Web Tool to try out Laika online
    • General cleanup of parser implementations and alignments between Markdown and reStructuredText parsers, making both of them much more robust
  • 0.2.0 (May 7, 2013):

    • Support for reStructuredText (full specification)
    • Concise and type-safe API for all reStructuredText extensibility options (directives, text roles)
    • New document tree nodes for tables, footnotes, citations, definition lists, internal links, comments, system messages, invalid elements
    • Render hints for document tree nodes in the form of the new Customizable trait
  • 0.1.0 (Jan 12, 2013):

    • Support for Markdown as input
    • Support for HTML and PrettyPrint as output
    • Customization hooks for renderers
    • Document tree rewriting
    • Various options for input and output (strings, files, java.io.Reader/Writer, java.io streams)
    • Generic base traits for markup parser implementations