Laika Documentation

Laika can be integrated into various environments depending on your needs:

• sbt Plugin: For version 1.x, ideal for build and CI pipelines (e.g., generating Scala project documentation).
• JVM Library: Supports Scala 3.3+, 2.13, or 2.12.
• Scala.js Library: Supports Scala.js 1.13+ applications. Note that in Scala.js, File/Stream IO, EPUB, and PDF output are not supported.

Laika supports a variety of markup languages and output formats:

Input Formats:

• Markdown (including GitHub Flavor)
• reStructuredText (including standard directives)
• HOCON (used for configuration and directive attributes)

Output Formats:

• HTML sites (based on templates)
• E-Books (EPUB & PDF) with auto-generated navigation

Laika also includes a lightweight default theme with configurable styling for sites, EPUB, and PDF output.

Many configuration types have been converted from case class to regular class (or trait) to allow for easier evolution.

Key changes to configuration patterns:

• Required Parameters: The apply methods now only accept required parameters.
• Optional Properties: Use the withXX pattern to set optional properties (e.g., myConfig.withProperty(value)).
• Defaults: For types with no required properties, use XX.defaults (if pre-populated by the library) or XX.empty (if not pre-populated).

The Theme API expands on ExtensionBundle by allowing you to pre-populate the input tree with templates and styles. This enables providing ready-to-use rendering styles (CSS, JavaScript, and templates) without requiring users to craft their own.

Laika includes a default lightweight theme called Helium, which provides default styles for web sites, EPUB, and PDF. You can often achieve desired results by simply tweaking Helium's settings.

You can override the output of a renderer for specific types of AST nodes while keeping the default behavior for others. This is useful when customization is coupled to a specific output format (e.g., adding a CSS class to an HTML tag).

For generic logic that should apply to all output formats, use [AST Rewriting] instead.

A custom renderer is defined as a PartialFunction[(Formatter, Element), String]. If the partial function does not match a specific node type, Laika falls back to the default renderer. If multiple custom renderers are provided, they are tried in the order they were added.

import laika.ast._
import laika.api.format.TagFormatter

// Example: Adding a 'big' class to emphasized text in HTML
val renderer: PartialFunction[(TagFormatter, Element), String] = {
  case (fmt, e: Emphasized) => 
    fmt.element("em", e, "class" -> "big") 
}

Laika allows extending text markup syntax via two primary methods:

1. Implementing Directives: Best for convenience when using a common syntax for declaring attributes and bodies. This does not require writing custom parser combinators.
2. Writing Parser Extensions: Best when you have highly specialized syntax requirements (e.g., a custom table format) or want the most concise syntax for frequent elements (e.g., #123 instead of @:ticket(123)).

Markup parsing in Laika is a multi-pass operation. It first identifies blocks (like blockquotes or lists) and then parses the text within those blocks for inline spans (like links or emphasis). Extensions can be implemented for either Spans (inline) or Blocks (structural).

Instead of relying solely on the physical file system, Laika uses a Virtual Tree Abstraction to organize markup documents, templates, and configuration files. This provides several advantages:

• Recursive Merging: You can specify multiple input directories. Laika will perform a recursive merge of these trees, allowing you to keep reusable templates, styles, and static files in separate locations from your primary markup files.
• In-Memory Content: You can generate content in-memory and assign it a virtual path. This allows you to 'mount' generated content at a specific location without writing it to the disk first, which is highly efficient for CI environments.
• Virtual Linking: Internal links (e.g., ../intro.md) are resolved based on virtual paths, meaning they can seamlessly reference both physical files and in-memory generated content.

Laika uses a lightweight template engine to customize the output of transformed markup documents. Templates allow you to specify where content from markup documents is inserted and add dynamic elements like navigation bars.

Key distinctions:

• Templates vs. Renderers: Templates control the structure and placement of content (e.g., where the body goes in an HTML shell). They do not control how individual AST nodes (like a bold tag or a link) are rendered. For that, use [Overriding Renderers].
• Templates vs. Themes: When using a theme (like Helium), it is often better to use the theme's high-level configuration options. Use custom templates only when subtle tweaks to a theme are insufficient or when working without a theme.

Laika processes documents through four distinct transformation phases. Understanding these phases is essential for knowing where to hook in your extensions:

1. The parsing step: Text markup and templates are parsed into a generic internal AST (Abstract Syntax Tree). This AST is format-agnostic.
2. The AST transformation: The initial AST is refined. Because parsers run locally (in parallel), nodes requiring global context (like internal references or auto-numbered footnotes) use a DocumentCursor to access other parts of the tree.
3. Applying templates to markup documents: The markup AST is inserted into the template AST at designated insertion points. This is essentially a second AST transformation.
4. Rendering: The final combined AST is rendered into specific output formats (e.g., HTML, PDF, EPUB). This is the only phase specific to a particular output format.