Laika v0.17.0 Release NotesRelease Date: 2020-10-31 // over 1 year ago
🆕 New Support for Versioned Documentation (#165)
- Allows to configure individual inputs (directories or documents) as versioned or unversioned.
- Writes versioned documents into a sub-path (e.g.
- Includes a version dropdown in the Helium theme to switch between versions.
- Dropdown is populated from JSON, therefore older versions see newer versions.
- Support for "smart linking" where the version switcher picks the same page in the target version when it exists.
📜 Position Tracking for Multi-Pass Parsers (#159)
- Previous releases only supported position tracking for single-pass parsers (e.g. CSS, HOCON, templates),
but not for multi-pass (text markup), where the 2nd and subsequent passes lost track of the position.
- Support for multi-pass tracking was introduced by replacing the old
📜 by an ADT (
SourceCursor), with concrete sub-types for recursive parsing (e.g.
that remember their relative position into the
- Formatting of parser errors for Markdown and reStructuredText was improved to carry line number information.
🔧 Configuration Enhancements (#161)
- New configuration options
laika.targetFormats, available for directory and document configuration,
which allows to restrict the output formats a document is rendered in.
- Allows to configure a document to only be part of the site output, but not the PDF and EPUB for example,
or, when specifying an empty array, to not be rendered at all, in case you intend to use
a document solely via the new
- Link Validation is aware of this configuration and prevents you from linking to a document that is available
in fewer output formats than the link source.
🆕 New Directives (#163)
@:embedallow to include other text markup documents or templates in the current document.
📜 The latter also allows to pass a parsed body element which can be referenced inside the included resources,
which may be useful for creating "master templates" that act as a frame for child templates.
🆕 New Link Validation API (#162)
DocumentCursorhas several new
validatemethods to validate internal targets by relative or absolute paths,
👍 allowing this previously internal logic to be used by custom rewrite rules or directives.
👌 Improved Fenced Code Blocks for Markdown (#164)
- Lifts the requirement of a preceding blank line to detect a code fence.
Previous changes from v0.16.1
New Default Theme for Sites, EPUB & PDF and an API for Theme Authors
🆕 New Lightweight Theme called Helium
- Ready-to-use styles for the 3 major output formats: HTML, EPUB, PDF
- Responsive design of the site output.
- Define font resources, color sets, layout and other details with the Scala configuration API for Helium
- Support font embedding for EPUB and PDF out of the box
and EPUB, search paths can be restricted if necessary.
- Obtain more low-level control over the output by overriding the theme's CSS.
- Includes an auto-generated main navigation bar and a page navigation with configurable depth.
- Anchors on mouse-over for headlines, providing the URL to the section.
- Favicon support.
- Support for font icons as well as a set of default icons included in the theme.
- Integrated download page offering the site content as EPUB and PDF.
- Website landing page tailored for software documentation sites.
🆕 New API for Theme Authors
- The Theme API allows to create 3rd-party themes by pre-populating the input tree with styles, scripts, images,
font resources as well as providing extensions for the Laika Core features in the form
of the existing
🆕 New API for freely composing inputs
- Individual files, in-memory strings or streams can now be freely combined and "mounted" to a logical path
within Laika's input tree.
- Add support for classpath resources.
- Add support for providing inputs as a pre-built document AST, bypassing the parsing step altogether.
- Supported for user code (when specifying the inputs to transform) as well as for theme authors.
🆕 New Directives
@:calloutproduces decorated text blocks with background color and icon.
@:imageenhances the options native markup provides by allowing to specify the intrinsic width and height
💅 of images to avoid layout shift in browsers as well as assigning a style for controlling the display size via CSS.
@:selectis a powerful directive to create alternative versions of your content, e.g. for Scala vs. Java APIs
🏗 or for sbt vs Mill build examples.
In the rendered website these choices are available via tabs, for EPUB and PDF they will lead to separate
artifacts containing only one of the choices.
@:sourceis a link directive, allowing to specify a fully qualified classname, similar to the existing
@:apidirective, but linking to the source (e.g. on GitHub) instead of the API documentation.
@:linkJScan be used in HTML template files in the
headsection for auto-linking
all CSS and JS files found in the input tree (or restricted to specific directories only).
@:todois a little helper directive to overcome the problem that Markdown does not have comment syntax.
Renderers will simply ignore the content of the directive.
👍 EPUB Support
- Tweak defaults to accommodate for the fact that some popular readers like iBooks do not support the full standard
0️⃣ for their navigation menus. Default navigation depth is now only 2 for EPUB output.
- Introduction of special suffixes to distinguish CSS for EPUB from site CSS:
*.epub.csswill only be used
*.shared.csswill be used for EPUB and site, while all other CSS files will only be used for the site.
👍 API Change for Theme Support
- All transformers, parsers and renderers from the
laika-iomodule are now provided as a cats-effect
This change was necessary as themes are themselves passed to transformers as a
Resourceas they might
require side-effecting initialization logic.
🏗 See the Migration Guide for the (trivial) changes that are necessary for code building transformers.
- EPUB: the library could produce invalid XML metadata files for the EPUB container under some circumstances,
e.g. a headline staring with a number or containing an ampersand.
excludeFromValidationflag was ignored in some scenarios.
- An AST rewrite rule returning an explicit
Retaincould override a
Replaceaction from a previous rule.
🚧 Project Maintenance
- Update dependencies to cats 2.2.0, cats-effect 2.2.0 and ScalaTest 3.2.2.
- Solely use sbt's slash syntax in Laika's build and all configuration examples for Laika's sbt plugin
- Remove all deprecated classes and methods.
- Remove legacy directive syntax that had been deprecated since 0.12.
🚀 This release is identical with 0.16.0 which had a broken