« Changelog History


Orchid v0.19.0 Release Notes

Release Date: 2020-02-23 // about 4 years ago
    • 👌 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.