1.0.0-M4

This is the penultimate (planned) milestone for the upcoming 1.0 release.

• Merging Features from 0.19.4

  This milestone merges the features introduced in version 0.19.4 to the 1.0 series, minus all deprecations which have been removed for 1.x. See the release notes for that version for details. The rest of these notes only highlight the aspects specific to the 1.0 milestone series.

• Changed Behaviour for Including CSS/JS

  The old default of using a global search path for automatically linking all CSS and JS files from the input sources is no longer active. Users need to explicitly configure at least one search path (via .site.internalCSS or .site.internalJS) for a resource scan to happen.

  The old behaviour was often unexpected (and users had to search for ways to disable it) and also came with the risk of overlapping search paths where a theme or extension adds their own resources. The new API allows more control in general (e.g. setting a condition per document for whether resources are linked or not).

  More details in #511.

• Dependencies

  • Updates Apache FOP to 2.9
  • All the updates introduced in 0.19.4

1.0.0-M3

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

The sole focus of this milestone was to convert public case classes to a format that can be evolved in a way that is binary-backwards compatible. Some other public case classes were converted to regular classes as structural equality was not well-supported anyway.

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

This release is not binary compatible with 0.19.x nor the previous milestone.

There are two more milestones planned before the first release candidate:

• M4 will simply merge up the upcoming 0.19.4 version once it is released and will be last milestone with the code bases largely in sync.
• M5 will then deliver all the repackaging work that became necessary by reducing the public API surface and leaving behind skeleton packages.

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)