Customizing Laika - Overview

Laika's Documentation comes with separate sections for "Customizing" and "Extending" Laika. While the line between the two is naturally quite blurry, the distinction is mostly meant to be between these two scenarios:

• Customizing Laika refers to the things you most likely want to tweak and adjust for a specific project.

• Extending Laika refers to the kind of re-usable extensions you might want to write as an in-house library or a 3rd-party open source extension.

This section deals with the former scenario.

Transformation Phases

In cases where you just want to tweak some minor details about how your site or e-book renders, you can use one of Laika's hooks into the various phases of a transformation.

For a better understanding of the customization options it is good to a have a rough idea about how a transformation in Laika is performed. It can be divided into 4 phases:

1) The parsing step. Text markup and template documents get parsed and translated into an internal AST. The AST is a generic abstraction of the document's structure and is not tied to any specific semantics of a particular input or output format.

2) The AST transformation. The original AST is only what each parser for the corresponding block or inline element can process locally, without access to other nodes or even other documents. One of the advantages of this design, apart from separation of concerns, is that parsers can run in parallel. As a consequence nodes like internal references or auto-numbered footnotes require further processing with access to a DocumentCursor that allows to access content from anywhere in the input tree.

3) Applying templates to markup documents. Since both are just AST structures, this step is merely a second AST transformation. The AST representing the markup document will be inserted into the node of the template AST that holds a reference to the content.

4) Rendering. As the last step the final AST obtained from the two previous transformation steps will get rendered to one or more output format. This is the only step specific to a particular output format, meaning the same AST structure obtained in 3) will get used as the input for the renderers of all formats.

Customization Options

The hooks that are the most likely candidates of helping you with smaller tweaks to a transformation are the following:

• Creating Templates: Hooks into phase 3 described above. A template lets you specify where the content from text markup documents gets inserted and allows to add additional dynamic elements like navigation bars.

• AST Rewriting: Hooks into phase 2 described above. The advantage of using this hook over tweaking renderers is that changes made to the AST are always reflected in all rendered output formats. So if your custom logic is not specific to the output format, you should prefer this option. Writing a custom rewrite rule requires pattern matching on the AST node you are interested in, therefore, you may also want to read about The Document AST.

• Overriding Renderers: Hooks into phase 4 described above. It allows you to override the default renderer for one or more specific AST node types, while falling back to the built-in renderers for all others. Overriding renderers also requires pattern matching on the AST node you are interested in, therefore, you may also want to read about The Document AST.