0.18.1

• Scala.js support: this is the first release published for Scala.js on Scala 3 (@armanbilge)
• Link validation now allows duplicate headers on the same page as long as no internal link points to them
• All tests have been migrated from ScalaTest to munit
• Improvements and fixes for the Helium theme
  • The content and landing pages now render properly in portrait mode on phones
  • The version dropdown now works correctly on unversioned pages
  • Anchor placement for section headers no longer overlaps with header text
  • The font for code now falls back to monospace for unavailable glyphs
• Other Bugfixes:
  • Parser inputs with Windows line breaks led to errors
  • mailto links were incorrectly validated as internal links
  • The laikaPreview task of the sbt plugin did not report the port correctly when launching (@daddykotex)
  • The laikaDescribe task of the sbt plugin failed in case of non-existing input directories
    (which is common when using Laika with mdoc)

0.18.0

• Migrate to cats-effect 3
  • Adjust public API in laika-io module by removing all usages of ContextShift and Blocker
    which are gone in CE3.
  • Remove the old .io(blocker) builder step as it is now redundant.
  • Simplify requirements to just Sync for sequential transformation and Async for parallel execution.
  • PDF support: remove the old callback hacks for integration with the blocking, synchronous ResourceResolver API
    of Apache FOP by using the new Dispatcher from CE3 instead.
• Support for Scala 3.0
• New Preview Server
  • The new laikaPreview task of the sbt plugin can be used to browse generated sites.
  • Includes auto-refreshing when input sources change.
  • Can also be launched via the library API, using laika.preview.ServerBuilder.
  • Introduces a new published module laika-preview that the sbt plugin depends on.
• New Directives:
  • @:path: Validates and translates a path in a template to a path relative to the rendered document the template
    is applied to.
  • @:attribute: Renders an optional HTML or XML attribute.
• Helium Theme:
  • Add support for dark mode to the Configuration API for EPUB and HTML output,
    allowing to specify a complete second color set for theme colors and syntax highlighting that becomes
    active when the user switches to dark mode in the OS or reader software.
  • Make the link of the home icon configurable.
  • Add the page background color to the configurable theme colors.
  • Add a "high-contrast" option for the top navigation bar (darker in light mode and lighter in dark mode).
• Icon Support:
  • Add new AST nodes for different kinds of icon sets: font icons, CSS icons (e.g. image sprites), inline SVG icons
    and SVG symbols (references).
  • New @:icon directive that allows to reference an icon by key in markup documents or templates.
• Versioning:
  • New renderUnversioned flag, that can be set to false when rendering older versions
    (e.g. from a maintenance branch) to ensure that unversioned files always come from the main branch (newest version).
  • Use existing /laika/versionInfo.json documents in the input directory as an alternative to scanning the
    target directory for indexing the content of older versions.
• Link Validation: new addProvidedPath method on InputTreeBuilder that adds a path representing a document which is
  processed by some external tool, making it available during link validation.
• PDF Support: upgrade to Apache FOP 2.6 (2.4 and 2.5 were both skipped as they had an issue with non-public dependencies
  in their POMs).
• EPUB Renderer: add support for JavaScript execution in EPUB documents
  • Scripting in EPUB requires a flag to be set for each scripted document in OPF metadata.
  • Indicators can be given in the EPUB template with the new laika.epub.scripted key,
    which has the values always, never and auto.
    The auto value which is also used in Helium's default template sets the flag whenever there are any
    documents in the input tree with the suffix .epub.js or .shared.js.
• Error Handling for Rewrite Rules and Cursor API
  • Change signatures of methods for registering rules in a bundle, rewriting a document or creating a cursor
    to include error handling (rule builders can now return an Either[ConfigError, RewriteRule]).
  • Use these new hooks in internal rewrite rules to validate configuration values used by the rules early.
  • Include key information in DecodingError.
• Error Reporting: When a parser error originates in a template the error formatter now includes the path info
  for the template instead of making the error appear as if it came from the markup document
• AST: add codeOptions property to CodeBlock element for potential tool integrations
• sbt plugin: The Laika/clean task now preserves some directories that will not be re-generated
  (e.g. api documentation, download directory and older versions in versioned documentation).
• Bugfixes
  • The HTML renderer did not apply versions to image URLs in case of versioned documentation
  • 0.17.1 introduced a regression where transforming empty strings caused an endless loop
  • In-memory string input sources could not be read more than once
  • The content of the @:fragment directive was ignored in many rendering scenarios

0.17.1

• New syntax highlighters for YAML, Haskell, Dhall and Alloy (contributed by @note - #174, #175, #176, #177, #181).
• AST: new companions for list and link types to reduce boilerplate and new RawLink type (#168, #179).
• Reduction of boilerplate in test suites by re-using common directory tree structures (#167).
• Publish sbt plugin to Maven Central instead of bintray to deal with the impending sunsetting of the latter.
• Include manual build and set up GitHub Actions in repository.
• Bugfixes
  • Versioning support in Helium theme: fix several issues where versioned path were rendered unversioned
    and vice versa; affected links to API documentation, e-book downloads and the favicon.
  • Fix incorrect merging of configuration instances when using InputTreeBuilder to manually assemble inputs.
  • Path.isSubPath no longer fails when the only difference is suffix or fragment (#169).
  • Markdown parser now supports literal spans with multiple backticks as delimiter (#170).
  • The date directive for reStructured text now excludes the time component by default to align with the spec (#180).
  • Whitespace before a configuration header in a markup file does no longer prevent detection of the header (#171).
  • Helium: don't generate a link to the markup source for programmatically generated pages (#178)

0.17.0

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

0.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
    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.

0.15.0

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.

0.14.0

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

0.13.0

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

0.12.1

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

0.12.0

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