Skip to content

1.0.0
Compare
Choose a tag to compare
@jenshalm jenshalm released this 16 Oct 17:25
· 96 commits to main since this release
v1.0.0
87b2aeb

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
Assets 2
Loading