1.2.0

This release is binary-compatible with the 1.x series.

It is a minor update that introduces a small number of new APIs as well as a handful of minor dependency bumps.

• New APIs

  • Promote internals of Helium's include directive to public API - #621
    This will make it easier to create equivalents of the @:includeCSS and @:includeJS directives outside of the Helium theme.
  • New overload for the Helium method for configuring the landing page - #620
    The new overload allows to configure the title of the documentation panel to avoid the previous, accidental hard-coding of text.

• Bugfixes

  • Do not overwrite explicitly assigned header ids by @milessabin - #614
  • Do not discard @:fragment sections in PDF output - #607
  • Merge @:fragment sections with the same name instead of silently dropping all but one - #606

• Minor dependency Bumps

  • Scala.js - 1.15.0 -> 1.16.0
  • cats-core - 2.10.0 -> 2.12.0
  • http4s - 0.23.26 -> 0.23.27

• Other Dependency Updates

  • Scala SDK 2.13.14
  • fs2 3.10.2

• Build & Test Dependencies

  • sbt 1.10.0
  • sbt-typelevel 0.7.2
  • sbt-mdoc 2.5.4
  • munit-cats-effect 2.0.0

1.1.0

This release is binary-compatible with the 1.x series.

It is a minor update that introduces a small number of new sbt settings and new APIs as well as a handful of minor dependency bumps.

• New sbt Settings
  Two new settings intended to fill functional gaps where tasks that are trivial for API users were difficult and cumbersome for plugin users.
  • laikaRenderers - A new setting that allows to define user-defined or 3rd-party renderers in addition to the builtin ones - #588
    Many thanks to @valencik for helping with testing this new hook in the context of protosearch integration.
  • laikaTreeProcessors - A new setting that allows to define AST processors that execute between parsing and rendering - #598
• Preview Server
  • New method ServerConfig.withBinaryRenderers for defining user-defined or 3rd-party renderers - #588
    These will be auto-populated for plugin users, but can be manually defined when the preview server is launched separately.
• Syntax Highlighting
  • Add a new diff highlighter - #601
• Minor Dependency Bumps
  • fs2 - 3.9.4 -> 3.10.1
  • http4s - 0.23.23 -> 0.23.26
  • Scala.js - 1.13.2 -> 1.15.0
• Scala SDK Updates
  • 3.3.3
  • 2.12.19
  • Skipping 2.13.13 due to the compatibility issues around the -Xsource option
• Other Dependency Updates
  • cats-effect 3.5.4
  • sbt-typelevel 0.6.7
  • sbt 1.9.9

1.0.1

This release is binary-compatible with the 1.x series.

• Fixes and enhancements for the Helium CSS
  • Use theme background color for version menu instead of hard-coding white - #583
  • Fill gaps in the CSS for the landing page (content-width, block-spacing, list styles) - #581
  • Fix margins for h1 headers without title class - #569
  • Code spans in links should always use the link color - #568
• Documentation
  • Fix scaladoc code sample for InputTreeBuilder - #578
  • Collection of minor fixes for the manual - #582
• Build / CI
  • Do no longer run mdoc with Java 8 which mdoc does no longer support - #560
• Dependency Updates
  • cats-effect 3.5.3
  • fs2 3.9.4
  • sbt-typelevel 0.6.5
  • sbt-mdoc 2.5.2
  • sbt 1.9.8

1.0.0

After 11 years of development Laika has finally matured enough to call a release 1.0.

In contrast to the 0.19 upgrade this is not a feature release. The primary focus of this version was to adjust the public API surface to allow it to evolve more easily in a binary-compatible way.

The published artefacts are nearly identical to the 1.0.0-M5 release. The release notes below cover all changes of previous 1.0 milestones.

---

Migrating from 0.19 to 1.0

It's recommended to first update to 0.19.5, if you haven't done this already, and address all deprecation warnings first. All deprecated APIs had been removed for 1.0.

For users who only use the library's configuration APIs the upgrade should be straightforward (in many cases a simple "Organize Imports" to adjust for the new package structure will be sufficient). Users who developed extensions might need further adjustments for some of the breaking API changes.

---

Changes in 1.0

• The library is now published under the org.typelevel organization

  All 0.x releases had been published under org.planet42 which will no longer be used in the future.

• Changed Behaviour for Including CSS/JS - #511

  This is a breaking change the compiler does not help with detecting. If you previously had custom CSS or JavaScript files auto-linked to your pages, you need to adjust your configuration (see the PR for more details).

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

• Breaking API Changes

  • New Package Structure - #533

    Cleans up the public API which had become fragmented after many types had been made private for 1.0. In laika-core the number of top-level packages has been reduced from 14 to 5. Apart from moving a lot of classes to new packages, many ADT type members have also been moved to their companion for better API navigation. In most cases a simple "Organize Imports" should be sufficient. See the PR for details.

  • Reduced public API surface - #452

    The number of public types have been reduced by about a quarter of the API surface compared to 0.19.x. Like many other changes for 1.0 the main motivation was to more easily evolve the library in a binary-compatible way. The removed APIs were so low-level that very few users should be affected by this change.

  • Many case classes are now regular classes - #482

    Past experience shows that classes used for configuration purposes evolve more frequently than most other APIs. For this reason many case classes have been converted to traits with private implementation types. The apply methods have been reduced to required parameters only. Optional properties can be set with the common withXX pattern. Types which don't have any required properties usually offer an XX.defaults or XX.empty entry point depending on whether it is pre-populated by the library or not.

  • Simplified Formatter APIs - #523

    Concrete formatter types like HTMLFormatter or FOFormatter are private now and their API has been unified under the two traits Formatter and TagFormatter. Several method signatures in TagFormatter have also been simplified for more concise renderer implementations. See the PR for details.

  • Removal of all deprecated APIs - #429

    For a more convenient upgrade, compile against 0.19.5 to see all deprecation warning before migrating.

• Build and Documentation

  • Publish API Documentation to javadoc.io - #535

    API documentation (via unidoc) is no longer hosted on GitHub pages, but instead available on javadoc.io, links are in the top navigation bar of the manual as usual.

  • Use sbt-typelevel for the build - #434

    The build will produce more warnings than the 0.x builds and fatal warning are now switched on for CI.

• Bugfixes that have not been backported to 0.19.x

  • Adjust parsing of file extensions to behave like other libraries - #526
  • Global link definitions should use case-insensitive matching logic - #541

1.0.0-M5

This is the final (planned) milestone for version 1.0. It marks the completion of all planned work for 1.0. Further updates leading to the final release will focus solely on issues reported by users.

From this point on it is recommended to start migrating to 1.x for end users. The release has matured in a way that you'll be shielded from big changes before the final release and migrating now will give you the opportunity to report issues before the final version is cut.

These are all the changes from M4 to M5:

• New Manual for 1.0

  The manual for the new version has been published under /latest, while the previous version has been moved to /0.19.

• Publish API Documentation to javadoc.io - #535 by @armanbilge & @jenshalm

  API documentation (via unidoc) is no longer hosted on GitHub pages, but instead available on javadoc.io, links are in the top navigation bar of the manual as usual.

• New Package Structure - #533

  Cleans up the public API which had become fragmented after many types had been made private in previous milestones. In laika-core the number of top-level packages has been reduced from 14 to 5. Apart from moving a lot of classes to new packages, many ADT type members have also been moved to their companion for better API navigation. See the PR for details.

• Simplified Formatter APIs - #523

  Concrete formatter types like HTMLFormatter or FOFormatter are private now and their API has been unified under the two traits Formatter and TagFormatter. Several method signatures in TagFormatter have also been simplified for more concise renderer implementations. See the PR for details.

• Bugfixes

  • Fix overeager validation of link target formats - #538
  • Adjust parsing of file extensions to behave like other libraries - #526
  • Global link definitions should use case-insensitive matching logic - #541
  • Merge fix for perfomance regression in preview server from 0.19.5 - #532

• Dependencies

  • Scala 2.13.2 + 3.3.1
  • fs2 3.9.2

0.19.5

This is an unplanned patch for 0.19 to address a performance regression. It is binary-backwards-compatible with previous 0.19 releases.

• Performance

  Fixes a performance regression in 0.19.4 where boot times for the preview server were significantly slower than in 0.19.3 - #524

• Dependencies

  Update fs2 to 3.9.2

0.19.4

This is the final (planned) release for 0.19. It is binary-backwards-compatible with previous 0.19 releases.

It introduces several new features and APIs, a small number of bugfixes as well as some deprecations to help with migrating to 1.0.

• New support for mermaid diagrams in the Helium theme. - #516

  Mermaid diagrams can now be included in standard fenced code blocks when using the default Helium theme.
  The diagram colors will automatically adjust to the theme color configured for Helium.
  This functionality is only available for HTML output, not EPUB or PDF.

• AST rendering in the preview server - #513

  The preview server now supports the rendering of the document AST for any page by adding the /ast path postfix. This enables users to inspect the model in cases they want to write render overrides or rewrite rules and are not sure what node types to match on.

• Better defaults & new API for configuring link validation - #432

  The defaults for link validation remain the same for plugin users, but are improved for API users where validation was on by default even when parsing a single input string that has no access to the surrounding directory, meaning that all validation was futile. It also comes with new configuration types to overwrite the defaults.

• New options for including CSS & JavaScript resources - #511

  Previous support was limited by only supporting local resources. The new APIs support linking external or inline resources, setting common attributes like defer and add support for conditional inclusion where the document AST or configuration can be inspected before deciding on whether a resource should be included.

• Better & safer AST builders - #436

  Introduces DocumentTree.builder as a safer and more convenient way to construct an AST model. The old apply entry point of the case class is deprecated. It was too low-level and error-prone due to the way several aspects of the model inherit properties from parents which might be missed with manual construction. And in 1.0 this type is no longer a case class.

• Spec compliance

  • Bullet lists in Markdown do no longer require a preceding blank line to be detected. (enumerated lists remain unchanged to match the spec). - #502
  • Support nested parenthesis in Markdown URLs - #514

• Bug fixes

  • Fix CSS for code spans in navigation items which were invisible in some cases. - #507 by @j-mie6
  • Properly support custom link text for link directives. - #515
  • Introduce substitution variable cursor.currentDocument.rawTitle that prevents the rendering of markup where not supported (e.g. in the <title> element). - #512

• Deprecations

  • introduces a small set of deprecations that will help with migrating to 1.0 - #518

• Dependencies

  • cats-core 2.10.0, cats-effect 3.5.1, fs2 3.9.1, http4s 0.23.23

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