All Versions
10
Latest Version
Avg Release Cycle
30 days
Latest Release
1408 days ago

Changelog History

  • v0.21.1 Changes

    June 18, 2020
    • 🛠 Fix bug preventing use of Netlify base URL
    • Properly use page themes for asset functions
    • 🛠 Fixes issue linking to sourcedoc elements in signature

  • v0.21.0 Changes

    May 29, 2020

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

  • v0.20.0 Changes

    March 30, 2020
    • 🆕 New Snippets plugin allows you to lookup and embed snippets from code, files, and even external webpages!
    • 👌 Improvements to Admin Panel styling. Forms and snippets located during the site build are care listed and can be previewed in the admin panel.
    • 👍 Allows Forms to be embedded with a new form tag, instead of only as Components as before. See docshere
    • 0️⃣ Replaces default accordion markup with details/summary tag for best usage in all themes
    • 👀 Tabbed TemplateTags can now be rendered dynamically! You can now use loops and conditionals to add individual tabs to the body of tabbed tags. See docs here.
    • 🏗 Both the base URL and your theme can now be set in config.yml, instead of needing to be set in your Gradle or Maven build scripts. See docs here.

    💥 Breaking Changes

    🚀 This release contains no breaking changes or deprecations of public, end-user features. Read on for important changes

    There have been some minor changes to the internal APIs. Most notable is that the ModularList primary constructor no longer accepts an injected OrchidContext. The context should instead be provided lazily when calling .get() to get the modular items from the list. In addition, I'm working on removing the requirement of an OrchidContext when creating OrchidReference objects. While it's still there for now, many of its public methods, like getServerPath()and toJSON(), and toString(), must be provided with a context when called instead of using the Context set in its constructor.

    0️⃣ In addition, Orchid is getting more strict on places where a non-null OrchidPage must be provided.ModularPageList.get() requires a non-null page, and Themes must have a page for each time it is pushed to theThemeService with theme.doWithCurrentPage(). This also means that Generators do not globally set Themes any more, and it is the responsibility of the Generator to wrap context.render calls with theme.doWithCurrentPage() using its default ThemeRelation. If you do not override startGeneration(), this will be done automatically, but if you are overriding startGeneration() you must make sure to add this functionality.

    🏗 Finally, the base URL is no longer available anytime during Orchid's lifetime. It is set at the start of each build, and thus is only available after indexing has started and when idle between builds. Attempting to get the base URL during Orchid startup will throw a NullPointerException.

  • v0.19.0 Changes

    February 23, 2020
    • 👌 Improve Asciidoc formatting. Specifically, other files relative to the source file can now be included. See caveatshere.
    • 🚀 Automatically add CNAME files to GithubPages deploys, if not already present in the deployed site. The CNAME value will be inferred from the base URL of the site during the deploy. See docshere.
    • ➕ Adds feedLinks metaComponent to Posts plugin, which adds <link rel='alternate'> tags to page heads, pointing to the generated feed pages. See docshere.
    • 🚀 Partial support for JDK 12+. Note that changes to the Javadoc since JDK 12 make the OrchidJavadoc plugin incompatible with JDK 12+. This will resolved in a future release, but for now you will have to run Orchid on a JDK less than 12 for it to work.
    • 🏗 The dev server now dynamically renders indexed pages, instead of directly returning files from disk. This will prevent pages from old builds from being rendered, makimg the dev server experience closer to what would actually be rendered in production. This is still a work in progres, and if you encounter issues, you can go back to the old functionality by adding the --legacyFileServer CLI flag.
    • Copy over images uploaded and referenced from GitLab wikis
    • 🛠 Various bugfixes for Kotlindoc plugin

    💥 Breaking Changes

    🗄 This version includes the removal of several features that were deprecated since 0.18.0, outlined below:

    • 🔌 Themes will no longer add search functionality automatically through the use of the legacySearch option. You must now migrate to the orchidSearch or algoliaDocsearch meta-component config instead, as described in theOrchidSearch docs.
    • 🚚 Usage of index.queryPages, introduced as a deprecated feature for backward-compatibility in 0.18.0, has now been removed. You must set up custom taxonomies now.

    🚀 In addition, there has been a moderate reworking of the resource APIs that are not backward-compatible. This is part of an ongoing effort to extract this functionality into a reusable library outside of Orchid, which will eventually live in the copper-leaf/arcana repo. The rest of these release notes are only relevant to folks writing custom plugins, and in particular, custom OrchidGenerators. Custom Components, Menus, Tags, and Functions are unaffected by these changes.

    Below is a summary of the changes to Orchid's OrchidResource, OrchidPage, and OrchidGenerator APIs:

    • Collections created by OrchidGenerators are now part of the model returned from startIndexing(), instead of being a discrete method on the Generator class itself.
    • Generators now run in 4 discrete stages instead of being ordered based on priority. This will enable future improvements to performance and greater clarity of the intention behind Generator ordering. There is a 1-1 mapping from older priority constants to new Generator Stages. The priority constants remain in place by name, but are now instances of OrchidGenerator.Stage enums instead of integer priorities. The stages are as follows:
      • Stage.WARM_UP (previously `PRIORITY_INIT): A Stage for Generators that produce pages that Content pages depend on, like registering global assets and warming up other caches which improve overall build performance.
      • Stage.CONTENT (previously `PRIORITY_EARLY): A Stage for Generators that produce content pages. These are pages that are generally standalone pages, only having relationships to other pages from the same Generator.
      • Stage.COLLECTION (previously `PRIORITY_DEFAULT): A Stage for Generators that collect Content pages into groups, taxonomies, etc, and optionally generate additional Content pages displaying those collections of pages.
      • Stage.META (previously `PRIORITY_LATE): A Stage for Generators that produce metadata about your site. These are not Content pages, and are usually intended for computers to read, not humans, such as sitemaps, search indices, etc.
    • OrchidPages must now be constructed with an additional RenderService.RenderMode constant in their constructor. This constant replaces calls to context.render*() calls, typically done from theOrchidGenerator.startGenerating() callback, and enables Orchid to determine how to render each page automatically without needing to override that method. Orchid will also render pages on-the-fly when running the dev server, which will eventually be able to significantly improve the development experience. The mapping of context.render*()calls to the new constants are as follows:
      • context.renderString() -> Removed, as it was a development-only API.
      • context.renderTemplate() -> RenderService.RenderMode.TEMPLATE
      • context.renderRaw() -> RenderService.RenderMode.RAW
      • context.renderBinary() -> RenderService.RenderMode.BINARY
    • The APIs for creating Resources has been partially rewritten. All of these classes have been rewritten in Kotlin and are now null-safe in Kotlin, and the contract is expected to be followed when used from Java. These APIs will continue to evolve as I continue to extract them to a separate library. The following are the main differences from the old APIs to the new ones:
      • All resources are now considered "freeable", but this is much more of an implementation detail now instead of something developers must think about. Resources now simply return an InputStream describing their contents, and the framework will take care of the rest, including caching and freeing that content as appropriate.
      • The interfaces for LocalResourceSource, ThemeResourceSource, and PluginResourceSource are now singleton_scope objects_. Internally, resource sources are now initialized with one of these markers. Instead of having separate context.get*ResourceEntry() or get*ResourceEntries methods, there is a single context method for each that accepts one of these Scope objects to filer resource sources by.
      • AbstractTheme no longer implements the OrchidResourceSource interface. Themes now return a resource source instead.
      • OrchidIntegrationTest can now take any type of resource in its test methods, instead of only being able to create String resources. In particular, the new classpathResource() function in the testing DSL loads a resource from the classpath (especially useful for using binary resources in integration tests).
      • Resources should now be passed to context.compile(). This allows compilers to know the source location of a resource they are processing, and can then import other resources relative to their source, such as when resolving includes from Asciidoc markup.
    • OrchidCompiler.compile() now writes to an OutputStream passed to it, instead of returning compiled String content.

  • v0.18.2 Changes

    January 22, 2020
    • 👀 Enables single-file Changelogs such as the Keep A Changelog format. See docs here.
    • Enables include directives in Asciidoc markup and changing SafeMode settings. Thanks to @tomb50 for help getting this set up!

  • v0.18.1 Changes

    December 19, 2019
    • ✂ Removes bible() function, since the API it used underneath has been shut down and the function was unusable
    • ➕ Adds Faithlife Reftagger meta-component
    • 👌 Improves YouTube tag to support full-width aspect ratios, with help from @DanySK
    • ➕ Adds Mermaid JS component to OrchidDiagrams plugin
    • 👍 Allows customization of sourcedoc module slug independently of module name

  • v0.18.0 Changes

    December 09, 2019

    🚀 Orchid 0.18.0 contains many new and breaking changes, which are briefly outlined in these release notes. Be sure to review the Migration Guide for a complete list of breaking changes and how to address them.

    🆕 New Features

    • 🆕 New OrchidTest library, for running integration tests of custom Orchid components.
    • Diagnosis Mode for detecting broken links in your site.
    • 📇 Meta Components improve workflow for adding asset-only components and other metadata to pages.
    • 🔌 Algolia Docsearch native integration
    • 📚 Introduction of experimental OrchidSourceDoc, to replace existing code documentation plugins (currently an opt-in feature).
    • ➕ Addition of Predefined Collection Archivesfor easier creation of archives based on familiar page collections.

    👌 Improvements and Bugfixes

    • 0️⃣ Components are now rendered using the Pebble embed tag by default, making it easier for themes to add wrapper markup
    • ✅ Orchid is now being tested on JDKs 8, 9, 10, and 11
    • itemId is now a static property of pages and can be viewed from the Admin Panel
    • 📚 Completely redesigned documentation site, with a new logo and a new domain
    • 🚚 Repo has been moved to the @orchidhd Github organization

  • v0.17.7 Changes

    November 04, 2019
    • 🆕 New Spotify tag added Orchid Writers Blocks plugin, to embed a Spotify track or playlist. Thanks@singularsyntax for the great addition!
    • 🏗 Great news for Scala users, you can now run Orchid from an SBT build! Thanks to the incredible work by @swaldman, adding the orchidSbtPlugin will allow you to run and serve Orchid builds directly from your existing SBT projects. Full setup instructions and commands can be found on the Quick-Start page.

  • v0.17.6 Changes

    October 14, 2019
    • ✂ Removes restrictions on filenames that can be used for assets. CSS assets no longer requires a .css extension, and likewise JavaScript assets no longer require a .js extension. It's up to you to make sure an asset is valid or not before it gets added to the page.
    • 🏗 When creating a Reference to a file that is not a child of the base dir, remove relative path segments so that it will be copied properly to the rendered site, and not outside of the build dir.
    • ➕ Adds kotlinPlayground component to the OrchidSyntaxHighlighter artifact, for converting Kotlin code snippets into runnable playgrounds.

  • v0.17.5 Changes

    September 24, 2019
    • 🛠 Fixed bug #312: Orchid terminates entire Maven build process when it completes
    • 🛠 Fixed bug #308: missing source directory prevents app from being served locally