Orchid v0.21.0 Release Notes

Release Date: 2020-05-29 // about 4 years ago
  • ๐Ÿ‘Œ Improvements

    • 0๏ธโƒฃ Experimental sourcedocs are now enabled by default
    • โž• Adds collectionPages menu item, which matches the same lookup behavior as the findAll() function. SeeMenus for usage.
    • 0๏ธโƒฃ Use 0.5 as default sitemap entry priority and always add priority to sitemap entries
    • ๐Ÿ›  Updates Kodiak version to 0.5.0, with several bugfixes for Dokka output, and preparation for generation of class hierarchy diagrams (still WIP)
    • ๐Ÿ“š Sourcedocs modules can now link to one another. Projects such as multi-module Java libraries or Kotlin multiplatform projects can now associate Orchid's documentation modules to one another, cross-linking to base classes or packages. See docs here
    • ๐Ÿ— Deprecation messages are now only shown in diagnose mode. A warning notifying of detected deprecation usage or diagnosed problems is now shown on normal builds.
    • Major improvements to asset management, external asset downloading, and asset inlining
      • Extra CSS/JS can now be configured as objects, and options like download and inline are available in extra CSS
      • A regression causing external assets to not download has been fixed
      • See docs here
    • ๐Ÿ†• New config DSL for setting up the config.yml in integration tests, and dramatically improved diagnostics for page html assertion failures

    ๐Ÿ› Bug Fixes

    • ๐Ÿ›  Fixes bugs with orchidSearch component
      • homepage is now included in search results
      • SourceDocs element names and comments are now included in search results
    • ๐Ÿ‘Œ Improves diagnostic output of OrchidTest APIs
    • ๐Ÿ‘Œ Support various different lettercasing for homepage file
    • ๐Ÿ›  Fixes several cosmetic issues with Copper theme
    • ๐Ÿ›  Fixes issue of -SNAPSHOT being included in the Orchid version logs
    • ๐Ÿ›  Formatting issues with Kotlindocs have been fixed

    ๐Ÿ’ฅ Breaking Changes

    ๐Ÿš€ This release includes 1 major breaking change to end-users, and the deprecation of several other end-user features which will be removed in a future release:

    • ๐Ÿš€ The --experimentalSourceDoc is no longer needed, as experiemental SourceDocs are now the default functionality. If you are still using the legacy sourcedocs, you can still use them for a short time longer, but you must now add the--legacySourceDoc flag to Orchid. Sites still building docs on legacy SourceDocs will not work without that flag, but you must now migrate to the new SourceDocs. Legacy sourcedocs will be removed entirely in the next major release.
    • ๐Ÿ’… {% styles %} is now included within the {% head %} template tag. The {% styles %} tag now does nothing, and in the next major version will be removed, causing template errors.
    • ๐Ÿšš {% scripts %} has been replaced by the {% body %} and {% endbody %} template tags. {% scripts %} will be removed in the next major version, causing template errors.

    ๐Ÿ”Œ In additional, there are several changes to both internal and public code APIs. The following are only of importance to developers making custom Orchid plugins, but can be ignored by anyone else as they do not impact end-user functionality.

    • ๐Ÿฑ The signature for fun loadAssets() in themes, pages, and components has been changed toloadAssets(delegate: AssetManagerDelegate).
      • In loadAssets, calls to addCss and addJs should now be made on that delegate: delegate.addCss("..."),delegate.addJs("..."). You can also use with(delegate) { ... } in Kotlin to reduce the boilerplate.
      • Previously, custom code needed to be written to prevent some external assets from being downloaded, but now theaddCss and addJs methods accept a configuration lambda or object with these available options. They are the same options available to extraCss and extraJs, so there is now difference between assets loaded inloadAssets() or attached from the extra assets.
    • ๐Ÿ— OrchidTest methods for directly selecting and testing HTML have been removed. Instead, you should use thehtmlHeadMatches and htmlBodyMatches methods to build DOM subtrees. However, diagnostic output is greatly improved for these matchers.
    • ๐Ÿ”Œ Meta-components can now render content to the page head, or the start or end of the HTML body. This is currently only reserved for future use with official Orchid plugins, but may be of interest to develoers making custom plugins in the Orchid community.
    • ๐Ÿฑ Methods from ResourceService for locating assets has been significantly improved. Rather than calling methods likegetResourceEntry() and locateLocalResource() on the context, they have now been moved into dedicatedOrchidResourceSources which can be gotten through the context. The ResourceService now only has methods to get the following types of resource sources:
      • getDefaultResourceSource() - Replaces getResourceEntry() and getResourceEntries(), which are now implemented on this default resource source. This will delegate the actual resource lookup to the site resources, theme, and registered plugins. They are also cached to improve lookup performance.
      • getFlexibleResourceSource() - Wraps the default resource source to add more flexible resource-lookup logic to it. Normal lookups must match both filename and extension, but flexible lookups will be abel to match by filename only, selecting a resource of any file extension. Replaces call to locateLocalResourceEntry() andfindClosestFile(). Note that findClosestFile() is deprecated as it does not delegate to the default resource source, and so should be avoided.
      • getTemplateResourceSource() - Wraps the default resource source to add template-locating logic to it. Replaces call to locateTemplate().
      • getDataResourceSource() - Wraps the default resource source to add functionality for loading data markup into a Map. Replaces call to getDatafile and getDatafiles().