All Versions
17
Latest Version
Avg Release Cycle
101 days
Latest Release
1499 days ago

Changelog History
Page 1

  • v0.17.0 Changes

    October 31, 2020

    🆕 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).

  • v0.16.1 Changes

    September 12, 2020

    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.

  • v0.15.0 Changes

    May 29, 2020

    New Navigation Features, Improved Error Handling & Rewritten, Expanded Manual

    • ✨ Enhanced Navigation Features
      • Internal references are now fully validated and dead links cause the transformation to fail by default.
      • Introduce global link definitions that allow to avoid repetition with centralized declarations of internal
        or external link targets.
      • Introduce new @:navigationTree directive that allows to combine auto-generated navigation trees
        🗄 with explicit manual entries. Deprecates the old @:toc directive.
      • Add new @:breadcrumb directive that produces a list of links from the root to the current document.
      • Introduce pluggable slug builder in ExtensionBundle to allow customizations of how a section headline
        is translated to an id.
      • Introduce "Link Directives", a new directive type that allows to define shortcuts for commonly used
        URL patterns, (e.g. @:rfc(2022)).
      • Add a new @:api link directive as a shortcut for linking to API documentation.
      • Change default names for title documents to README.<suffix> for the input for better GitHub integration
        👍 and index.<suffix> for the output for better site navigation.
        🔧 Defaults can now be overridden in configuration.
      • Add methods for navigating siblings in Cursor API for document trees.
      • Laika now always picks the first header as a title, even when subsequent headers are on the same level.
      • Improved precision in detecting ambiguous references.
      • Internal overhaul/rewrite of the link resolver algorithm which was still the original design from 2013
        and degraded in clarity over several feature additions.
    • 🔧 Configuration
      • Introduce programmatic ways to declare all global configuration for both, sbt plugin and library API,
        🔧 which now allows to completely avoid configuration files unless per-directory configuration is required.
      • Change HOCON configuration keys to always be in a namespace (e.g. laika.title or cursor.currentDocument),
        to reduce the likeliness of name clashes with user-defined variables.
    • Error Handling
      • The presence of invalid nodes in the document AST before rendering now always triggers an abortion
        of the transformation with all messages from invalid nodes listed in the error result.
      • The new default behaviour can be overridden in configuration to switch to "visual debugging" where
        invalid nodes are rendered in their original position in the result.
    • 🔄 Changes in the Document AST related to navigation enhancements
      • Merge the functionality of CrossLink into InternalLink
      • Merge ExternalLink and InternalLink to SpanLink
      • Split Temporary marker trait into Unresolved and Hidden
    • Manual
      • Complete rewrite of the manual which still had its initial structure from 2012.
      • Better separation of tutorial-style from reference-style sections.
      • New chapters about Laika's parser combinators, HOCON API, design goals, configuration options,
        📜 navigation features, writing parser extensions and adding new syntax highlighters.
    • 🛠 Bugfix
      • The combination of the laikaSite task with the laikaIncludeEPUB setting led to a zero-byte result.

  • v0.14.0 Changes

    February 28, 2020

    Introduce Support for Scala.js

    • 👌 Support for Scala.js 1.0 for the laika-core module:
      • Brings the complete functionality of Laika to Scala.js with the only
        👍 exceptions being File/Stream IO and support for PDF and EPUB output
      • Eliminate the last, semi-hidden usages of Java reflection to enable Scala.js support
      • Avoid use of java.time.Instant in the shared base to not force another heavy dependency
        on Scala.js users
    • Laika's integrated syntax highlighting:
      • Add support for Dotty, JSX/TSX, SQL, EBNF, Laika's own AST format
    • 📜 Parser APIs:
      • Introduce PrefixedParser trait to make span parser optimizations implicit
        for 90% of the use cases and no longer require the developer to explicitly
        supply a set of possible start characters for the span
      • Introduce new parser for delimiters that generalizes typical checks for preceding
        📜 and following characters in markup parsers (e.g. delimiter("**").prevNot(whitespace)),
        📜 to reduce boilerplate for inline parsers
      • Introduce shortcuts for very common usages of text parsers (e.g. oneOf('a','b') instead of
        anyOf('a','b').take(1))
      • Expand the API of the Parser base trait: add source method for obtaining the consumed
        📜 part of the input instead of the result of the parser, and count to obtain the number of
        consumed characters
      • Introduce laika.parse.implicits._ for extension methods for common parsers, e.g.
        .concat, mapN.
      • Introduce shortcut for repeating a parser with a separator
      • Deprecate all APIs that relied on implicit conversions
      • Deprecate some of the rather cryptic symbol methods on Parser in favor of named methods
      • DelimitedText does no longer have a type parameter
    • AST changes and improvements:
      • Introduce RelativePath as a separate type in addition to the existing Path type
        which is now only used for absolute paths
      • Introduce a range of shortcut constructors for Laika's AST nodes, that allow you
        to write Paragraph("some text") instead of Paragraph(Seq(Text("some text")))
        for example
    • Directives:
      • Cleaner syntax for default attributes which are no longer part of the HOCON
        attribute block for named attributes
    • Demo App:
      • Cleanup from six to two (bigger) panels for improved usability
      • Use Laika's own syntax highlighting in the output
      • Allow to switch from JVM execution to Scala.js
      • Move from Akka HTTP to http4s
      • Integrate source into Laika's main repository
    • 🛠 Bugfix:
      • Syntax highlighting for interpolated strings in Scala was broken in 0.13.0
      • Fix a flaky test that relied on the ordering of HashMap entries

  • v0.13.0 Changes

    January 26, 2020

    New Integrated Syntax Highlighting

    • 📜 Introduce syntax highlighting based on Laika's own parsers
      • Resulting AST nodes for code spans are part of the document AST and
        can be processed or transformed like all other nodes
      • Works with any renderer, including PDF
      • Initially supported are Scala, Java, Python, JavaScript, TypeScript,
        HTML, CSS, XML, JSON, HOCON
      • Convenient base parsers for common syntax like string and number literals
        or identifiers to facilitate development of new syntax highlighters
    • 📜 HOCON parser: add support for include statements, this final feature addition
      👉 makes Laika's HOCON support fully spec-compliant
    • 🆕 New transformation hooks in the laika-io module for parallel transformers:
      mapDocuments(Document => Document), evalMapDocuments(Document => F[Document])
      and the corresponsing mapTree and evalMapTree
    • 📜 Transformer introspection: introduce describe method for parsers, renderers
      🔌 and transformers and laikaDescribe setting in the sbt plugin that provides
      formatted information about the transformer setup and installed extensions
    • 🔌 sbt plugin: improved accuracy for caching logic for EPUB and PDF output
      that still works when the artifact name or version changes
    • ⬆️ Upgrade dependency on cats-core to 2.1.0

  • v0.12.1 Changes

    December 01, 2019

    Fixes and Improvements for HOCON Parser

    • 📜 HOCON parser
      • Significant improvements for error messages in the parser (#108)
      • Fixes for nested self references (#112), missing optional self references (#109),
        and objects without '=' or ':' separator (#104)
    • 📜 Parser Combinators: The '|' alternative parser now keeps the failure with the
      most processed characters and not the last one, for improved error messages
    • 🛠 Fix for script tag with attributes not being recognized in verbatim HTML in Markdown

  • v0.12.0 Changes

    October 30, 2019

    New laika-io Module, Full Referential Transparency, Integration with cats-effect

    🚀 This is a breaking release, for a full migration guide, see the Migration Guide

    • 🆕 New laika-io Module
      • Functionality extracted from existing laika-core module
      • Contains File/Stream IO, EPUB output, Parallel transformations
      • Based on cats-effect type classes (in "Bring-Your-Own-Effect" style)
      • Leaves laika-core pure, preparing it for later support for Scala.js
    • Referential Transparency
      • No method in the public API throws Exceptions anymore
      • The result of pure operations is provided by instances of Either
      • The result of side-effecting operations is provided by a return type of F[_],
        an effect type from cats-effect
      • Eliminated all uses of runtime reflection
    • 🔄 Changes to the APIs for creating and running parsers, renderers and transformers
      • Necessary due to the changes listed above
      • See the migration guide for details and examples
    • 🔄 Changes to the Directive Syntax in Templating
      • The syntax of separators for the attribute and body sections have changed
      • HOCON syntax is now used for attributes
      • The old syntax is still supported, but will be removed at some point before the 1.0 release
    • 🔄 Changes to the Directive DSL for creating directives
      • attribute(Default) is now defaultAttribute
      • body is now either parsedBody or rawBody
      • Type conversions happen with the new as method: attribute("title").as[String],
        based on the ConfigDecoder type class that is also used for the new Config API
      • Named body parts have been replaced by the more flexible Separator Directives
      • The built-in helper for mapping directive parts with different arity has
        been replaced by cats' mapN
    • 🔨 Refactoring of AST Rewrite API to be fully type-safe and avoid runtime reflection and exceptions.
      • Return types are now more explicit (e.g. Replace(newSpan) instead of Some(newSpan))
      • Rules for rewriting spans and blocks get registered separately for increased
        type-safety, as it is invalid to replace a span with a block element.
    • 🔨 Refactoring of the Render API to be referentially transparent
      • Also applies to the API for registering custom renderers for individual AST nodes
    • 🆕 New Config API and built-in HOCON parser
      • Removed the dependency on the Typesafe Config library and its impure Java API
      • Added a new lightweight and pure HOCON parser as part of laika-core,
        👌 supporting the full spec except for file includes (for now).
    • ✨ Enhancement for the DocumentTree API
      • The result of a tree parsing operation is now a new type called DocumentTreeRoot
      • It has a coverDocument property and contains the recursive tree structure of the parsed content.
      • Each DocumentTree in the structure now has an explicit titleDocument: Option[Document] property for more explicit content organization in e-books.
      • Properties that previously held references to streams and other impure data had been
        ✂ removed from the pure content model (e.g. DocumentTree.staticDocuments).
    • 🐛 Bug fixes for fenced code blocks with blank lines in GitHub-Flavored Markdown
    • Markdown: Properly render JavaScript in <script> tags in verbatim HTML

  • v0.11.0 Changes

    June 12, 2019

    Support for Output in the EPUB Format

    • 🆕 New Renderer for producing EPUB containers
    • 🆕 New laikaEPUB task in the sbt plugin
    • 🆕 New laikaIncludeEPUB setting for the laikaSite task
    • 👌 Support for cover images for EPUB and PDF
    • 👌 Support for document metadata (author, language, date, etc.) for EPUB and PDF
    • 👌 Support for title pages per chapter
    • ⚡️ Backwards-compatible to 0.9.0 and 0.10.0 - if you update from earlier versions, please see
      🚀 the release notes for 0.9.0 for migration

  • v0.10.0 Changes

    December 01, 2018

    Support for GitHub Flavored Markdown

    • 🆕 New Markdown parser extensions for GitHub Flavour:
      • Tables
      • Fenced Code Blocks
      • Auto-Links
      • Strikethrough
    • Preparing for Scala 2.13
      • Adjust use of Collection API for breaking changes and deprecations in 2.13
      • Replace use of parallel collections with custom executor
      • Release will follow once 2.13 is final
    • 🔧 Level of parallelism of transformations is now configurable
    • ⚡️ Fully backwards-compatible to 0.9.0 - if you update from an earlier version, please see
      🚀 the release notes for 0.9.0 for migration

  • v0.9.0 Changes

    September 15, 2018

    Introduction of the ExtensionBundle API

    • 🆕 New ExtensionBundle APIs allow to bundle extensions into a single object for easier reuse. Supported extension hooks include directives, markup parser extensions, rewrite rules, custom renderers, document type matchers, alternative parsers for stylesheets, templates or configuration headers and default templates per output format. For migrating from 0.8 extension hooks, see #56.
    • ⬇️ Reduced number of settings and tasks in the sbt plugin, by using the new ExtensionBundle API for sbt settings. The most common tasks and setting remain unchanged, for users of the lower level extension settings of the plugin see #65 for migration instructions.
    • 👌 Improved package structure to reduce number of required imports. For simpler use cases a global "organize imports" should suffice for migration, for all other cases see #66.
    • 🚀 The changes listed above fix some of the design issues of the very early releases from 2013/14 and bring the API closer to the 1.0 API. Upcoming releases are expected to have a much lower number of breaking changes, if any, as they are mostly feature additions.