1.0.0-M2

This is the second milestone for the upcoming 1.0 release with the major focus of making longterm binary compatibility feasible.

The sole focus for this milestone was to reduce the public API surface. The number of documentable templates reported by unidoc went down from 1206 for version 0.19.3 to 892 for version 1.0.0-M2, meaning about a quarter of the public API could be removed. Of course this is a breaking change, but the removed APIs were so low-level that very few users should be affected by this change.

The details of this work are kept in #452 which links to the 12 individual PRs that the work had been delivered with.

This release also includes all changes released with version 0.19.3, but it is not binary compatible with it (nor with the previous milestone).

0.19.3

This release is binary-compatible with previous 0.19.x releases.

• Helium UI
  • Fixes an issue where the selection of the color set for Helium's UI components was broken. - #456
    It has two style sets, one for light backgrounds and one for dark ones, but in some scenarios
    the wrong colors were chosen:
    • When setting .site.topNavigationBar(highContrast = true) in Helium config.
    • In portrait mode on phones where some components move from the top bar to the left sidebar.
    • When choosing a light background gradient for the landing page.
• Core Parser
  • Fixes a broken boundary check in Parsers.lookAhead - #444
• Code Cleanup
  • Reduces the number of compiler warnings (even though only the new build on the main branch causes them to surface) - #445, #446, #447
• Dependencies
  • Scala.js 1.13.2, http4s 0.23.22

1.0.0-M1

This is the first milestone for the upcoming 1.0 release with the major focus of making longterm binary compatibility feasible.

• Artefacts are now published under a new organization
  • They are now published under org.typelevel to reflect that Laika is now a Typelevel Organization project. For the plugin use addSbtPlugin("org.typelevel" % "laika-sbt" % "1.0.0-M1"), for the library modules the org id needs to be changed in the same way.
  • Further maintenance releases for 0.19 will continue to publish under org.planet42.
• CI-based release process by @armanbilge - #434, #435, #441, #451
  • Laika's build now uses the sbt-typelevel plugin.
  • Defaults for scalacOptions are picked up from sbt-typelevel, you will see more warnings than on the 0.19 branch.
  • Fatal warnings are now switched on for CI.
  • Code cleanup up to avoid compiler warnings in #442, #443, #448, #450, #455
• API Changes
  • Several traits in the AST model are now sealed - #449
  • All APIs that had been deprecated in 0.19 have been removed - #429
• Dependencies
  • Update Apache FOP to 2.8
  • Scala.js 1.13.2, http4s 0.23.22

The functionality of this release is largely identical with 0.19.2, but not binary-compatible with it.

0.19.2

This release is binary-compatible with previous 0.19.x releases.

• Syntax Highlighting
  • Adds a new highlighter for shell/bash syntax by @i10416 - #422.
• Bugfixes
  • Reverts a regression in 0.19.1 where the font size for code blocks was significantly smaller than in 0.19.0 - #420.
  • When transforming a single input string the transformer does no longer attempt to translate the path suffix
    for internal links - #415.
  • Several fixes for code samples in the manual and API documentation by @zhongl - #416, #417.
• Dependencies
  • All Typelevel dependencies have been updated to versions compatible with Cats Effect 3.5.0 (fs2 3.7.0, http4s 0.23.19). The Cats Effect update includes an important change to the cancellation semantics of the Async#async and IO.async methods. Please check the Cats Effect release notes for v3.5.0 for more details.
  • Updates Scala 2 versions to 2.13.11 and 2.12.18.

0.19.1

This release is binary-compatible to 0.19.0.

• Build, Documentation & Project Setup
  • Fill some gaps left by still mostly running the original 2012 setup and make Laika more contributor-friendly by integrating scalasteward (#340), scalafmt (#377), mima (#352), mdoc (#390) and adding a code of conduct (#339).
  • Add imports to the code samples in the manual.
  • A CI-based release process will follow in the 1.0 milestone series which will begin in the coming months.
  • None of these changes are directly reflected in the binary artefacts of this release.
• Helium Theme
  • Switch the default code font from Fira Code to Fira Mono to avoid unwanted ligatures in code samples (#393).
  • Introduce helium.site.pageNavigation.keepOnSmallScreens configuration attribute that allows to keep the page navigation on small screens, moving it to the top of the main content pane (#392).
  • Fix the size for code spans in headlines and other places that do not use the standard body font size by using relative sizes by default for HTML (#378) and PDF (#399). EPUP output was not affected as it has always used relative sizes.
  • Add the Mastodon logo, available via HeliumIcon.mastodon in code and @:icon(mastodon) in templates (#403).
• Core Renderer and Transformer
  • Fixing a regression introduced in 0.19.0 where the pure/standalone Renderer and Transformer implementations that transform a single string input drop the configuration that has been specified by the user in the builder (#401). The sbt plugin and the transformer for an entire input tree/directory were not affected, as they use a different code path to apply user configuration.
• Spec Compliance
  • Markdown: support spaces in link destinations inside angle brackets (e.g. [link](<some image.jpg>)) - #385
  • PDF: avoid filtering of inheritable XSL-FO attributes when they are not processed by the node they are placed in, as they may be processed by nested tags instead. In practice this issue meant that attributes assigned via Laika's CSS for PDF functionality were ignored in some cases. (#400)
• Updates
  • cats 2.9.0, cats-effect 3.4.9, fs2 3.6.1, http4s 0.23.18

0.19.0

This is the first major update that is primarily driven by user feedback and integrator's needs and not by the maintainer's endless backlog, therefore the list of changes is scattered over many features areas.

• Helium Theme
  • Template modularization - when custom templates are required they can now be added for just a portion of the page - e.g. head, main navigation, top navigation bar, etc. - #304.
    This reduces potential issues when core theme changes are not regularly merged up with custom templates.
  • Add support for canonical links
    • Can be set manually via laika.metadata.canonicalLink in configuration headers in text markup documents - #283.
    • Will be set automatically in versioned documentation if one version is marked as canonical in config - #286.
  • Helium now works properly with strict mode switched on - #333.
    This mode is supposed to only remove all extensions from text markup parsers that go beyond their respective specs, but the implementation previously also aggressively excluded several unrelated extensions.
  • Smarter defaults for the home link and better error messages when no suitable target can be found - #325.
  • New UI components - programmatically add version switcher menus, generic menus or link groups to the UI - #319, #321.
  • Expanded Helium Config API
    • Customize the left/main navigation pane (depth, additional links) - #328.
    • Customize the page navigation or exclude it from individual pages - #330.
    • Customize the version switcher menu (labels, additional entries) - #324.
    • Specify footers via config API - #329.
    • Link CSS or JavaScript to individual pages only via HOCON config headers in markup documents - #326.
    • Add a new placeholder to the landing page template for placing UI components right beneath the subtitle - #332.
    • The same config method can now be invoked multiple times without omitted arguments resetting to defaults - 9b94472.
    • Some properties like those for navigation links now accumulate, so that a user can add to links pre-populated by a theme - 9b94472.
  • Helium CSS
    • Render more style classes to allow for more fine-grained custom CSS, e.g. the name of the icon in case of icon links or the name of the directive in case of link directives - #327.
    • Improved styles for the main/left navigation panel (some styles were missing causing the hierarchy to disappear) - #323.
    • Fixes for the top navigation bar (where some link types were not properly centered and sized) - 67679d3.
• Standard Directives
  • Add new @:target directive which in contrast to the now deprecated @:path directive also supports external targets -#251.
  • Add new @:date directive for rendering formatted dates and times in text markup or templates - #276.
• Syntax highlighting
  • Add support for Dart - #254 by @i10416.
• Markdown Spec Compliance
  • atx-headers (those starting with #) do no longer require a preceding empty line to get recognized - #334.
• Link Validation
  • When transforming versioned documentation, exclude links to other versions from validation as those are usually not available as input source - 4acf7d5.
• Navigation
  • Add support for laika.excludeFromNavigation flag in HOCON configuration headers, causing a page to be transformed like other pages, but excluded from any auto-generated navigation structures - 8292832.
• Theme APIs
  • Add ThemeProvider.extendWith(ThemeProvider) and Helium.extendWith(ThemeProvider) for creating themes that depend on existing themes - #270.
  • Add Theme.descriptor and include it in the output of laikaDescribe - b113aee.
• Extension Points
  • Add new extension point PathTranslator to ExtensionBundle that allows to customize how paths of input documents are translated to paths of output documents - #299.
  • Add PrettyURLs extension based on this new extension point - #300.
    It will translate the inputs into a structure that allows to create links to pages without the .html extension. In some tools this is default behaviour, but with Laika the new extension must be enabled explicitly.
• Migrate laika-io module to fs2 - #281.
  • As a consequence, some high-level user API change requirements from Sync to Async - #280.
  • Introduce new FilePath API that is aligned with Laika's virtual path API - #284.
  • Deprecate all public API that expects a java.io.File argument - #290.
• Document AST
  • Introduce a more fine-grained rewrite phase model - #302.
    This is a larger internal refactoring that removes a whole range of old limitations when writing custom directives. In most circumstances directives are now allowed to dynamically add to the document structure (e.g. by introducing headers that are reflected in navigation structures). See also the related bugfix below and the details in the PR description.
  • Add convenience methods to several node types (e.g. Document.appendContent(Block*), DocumentTree.appendContent(TreeContent*)) - #271.
  • Split date metadata into datePublished and dateModified - #277.
• Preview Server
  • Switch http4s from blaze to ember backend - #260 by @armanbilge.
  • Split laikaPreview task in sbt plugin into a builder and a launcher, so that integrators like sbt-typelevel can reuse the build step while modfiying the launcher - #273.
• Bugfixes
  • Headers or other nodes with ids disappear when created in a custom directive - #289.
  • Title documents generate duplicate nodes in a breadcrumb component - #297.
  • laikaDescribe in the sbt plugin is now a task again, as a setting will log stale output from previous directory scanning - 7143abc.

0.19.0-RC1

The final release is identical to the RC apart from an upgrade to Scala.js 1.10.1.

Please see the release notes for 0.19.0 above.

0.18.2

• Fixes and improvements:
  • Link references within directive bodies (e.g. a @:callout component) were not resolved. (#263)
  • When using versioned output, the document versionInfo.json was still rendered when the renderUnversioned flag was set to false, even though the document is unversioned itself. (#266)
  • Several variable substitutions like cursor.nextDocument.relativePath were pointing to the markup sources
    and not to the rendered output, even though the latter is much more commonly needed for rendering links.
    This release deprecates the old variable names ending in .relativePath and .absolutePath and replaces them with .path (pointing to the output document for rendering links) and .sourcePath (pointing to the
    markup sources - the existing behaviour, but with a clearer name). (#262)

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