« Changelog History


Laika v0.17.0 Release Notes

Release Date: 2020-10-31 // over 3 years 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. /0.17/...).
    • 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 ParserContext type
      📜 by an ADT (SourceCursor), with concrete sub-types for recursive parsing (e.g. BlockSource or LineSource),
      that remember their relative position into the RootSource.

    - 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 @:include directive.
    • 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)

    • @:include and @:embed allow 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)

    • DocumentCursor has several new validate methods 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.

    🛠 Bugfixes

    • One of the default fonts (Lato) in the Helium theme had a http URL and thus did not work over https (#160).
    • selectDocument(Path) on DocumentTree did not work for title documents, which also caused issues for
      navigation directives when used on input trees with title documents (#166).

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
    • No dependency on 3rd-party CSS or JavaScript frameworks, just a minimal amount of hand-crafted CSS and JS.
    • 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
    • Supports auto-linking of all CSS and JavaScript files from your input tree in the HTML output for websites
      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 ExtensionBundle API.

    🆕 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

    • @:callout produces decorated text blocks with background color and icon.
    • @:image enhances 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.
    • @:select is 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.
    • @:source is a link directive, allowing to specify a fully qualified classname, similar to the existing
      📚 @:api directive, but linking to the source (e.g. on GitHub) instead of the API documentation.
    • @:linkCSS and @:linkJS can be used in HTML template files in the head section for auto-linking
      all CSS and JS files found in the input tree (or restricted to specific directories only).
    • @:todo is 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.css will only be used
      for EPUB, *.shared.css will 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-io module are now provided as a cats-effect Resource.
      This change was necessary as themes are themselves passed to transformers as a Resource as they might
      require side-effecting initialization logic.
      🏗 See the Migration Guide for the (trivial) changes that are necessary for code building transformers.

    🛠 Bugfixes

    • 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.
    • The excludeFromValidation flag was ignored in some scenarios.

    - An AST rewrite rule returning an explicit Retain could override a Replace action 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 laika-pdf artifact.