Monthly Orchid Update (7 Part Series)
Ah February, a month to celebrate love in all of its meanings: Valentines Day to celebrate love with your significant other, Black History Month to love and celebrate those different from us, and for Orchid, hippie love with new support for the Groovy programming language.
This is a monthly newsletter around Orchid, the newest and best static site generator for the JVM. There is a growing need to keep the community up-to-date on all the happenings around Orchid, and here I will share Orchid's progress during the previous month! Follow along with this series to stay on top of Orchid's newest features, track adoption on Github, and see who's using Orchid!
A beautiful and truly unique documentation engine and static site generator.
Orchid is a brand-new, general-purpose static site generator for Java and Kotlin, with a focus on extensibility and aimed at developers looking to improve their technical documentation. Orchid was born out of a desire for better-looking Javadocs and frustration with how difficult is it to manage large Jekyll sites and keep it up-to-date with your code.
Orchid supports a variety of plugins, including a wiki, static pages, blogs, and much more. It aims to have high compatibility with many of the existing static site generators, such as Jekyll, Gitbook, and Hugo, so that migration to Orchid is painless. And if you can't find a plugin to do what you need, Orchid provides an intuitive way to add your own private plugins and a rich API so you can make your site as beautiful and unique as an Orchid.…
As of the time of writing, Orchid is at 157 stars on Github. This was a really great month, with Orchid's new features and a blog post here garnering quite a bit of attention. Thanks for all the support!
After releasing 0.16.0, I published a post here on Dev.to detailing how to use Orchid to document Kotlin projects from beginning-to-end. It got quite a bit of attention and is definitely the best place to start if you're wanting t get started using Orchid for any of your projects. Be sure to check it out if you haven't already!
Orchid is now at version 0.16.1, a bugfix version after 0.16.0, which brought with it a ton of cool new features that I teased with last month's entry. All of these features have been released and are ready for you to use!
The theme I built for my own site, now you can use for yours! Based on Bulma, this theme is great for showcasing the best projects for your portfolio, but is equally good for documentation.
After setting up many of my other library projects with Orchid documentation, I've noticed myself adding the same plugins over and over to each project. To make it easier for others to get started with Orchid as a documentation tool, I've created a new Bundle,
OrchidDocs, which contains the following plugins:
OrchidCore: The core Orchid framework
OrchidEditorial: A default theme (subject to change in a later version)
OrchidPages: Static pages to hold changelogs, contact forms, project license, etc.
OrchidWiki: The full wiki documentation for the site
OrchidForms: Easily add contact or bug report forms
OrchidChangelog: Manage project versions, and update Github releases automatically on deploy
OrchidSearch: Enable full-text search of your docs
OrchidDiagrams: Describe your project with diagrams and flow charts
Delivered by request, Groovy will be an officially-supported language for Orchid code documentation. The Groovy plugin allows you to easily document your Groovy and Java source code and embed it in any Orchid theme you like.
Orchid is currently in the aftermath of releasing a major version, which typically means focusing on bugfixes, tests, and documentation. You can expect increasing stability and theme improvements over the next few weeks/months.
In addition, adding the Groovydoc plugin helped me understand better how Orchid should handle code documentation, and work is underway to greatly improve this for all languages. Work is underway that will make it significantly easier to add additional programming languages that Orchid can work with, and also make it easier and more flexible for you to document your projects. You can follow the work toward this goal in the following issue on Github.
This is the beginning of a major reworking of how Orchid handles code documentation.
Instead of having separate plugins which each provide their own generators/templates/menu items/etc., Orchid should have a single plugin that does the work of configuring and generating all the Orchid stuff needed. The language plugins then just need to provide adapters to that common "code documentation" model to work.
Specifically, the copper-leaf/dokka-json will provide a common interface and configuration strategy that the main Orchid plugin will work with, and the individual languages in that repo each provide the adapters needed to work with it.
By including the main code documentation plugin and the individual language adapters needed, no additional Orchid-specific work needs to be done to support new languages. All that would be required is creating a language model that conforms to the copper-leaf/dokka-json common interface, which is tool-agnostic.
- [ ] 1. Get all languages currently supported by Orchid moved to the model used in the copper-leaf/dokka-json project
- [X] 1.1. Java
- [X] 1.2. Kotlin
- [X] 1.3. Groovy
- [ ] 1.4. Swift
- [ ] 2. Create a common interface in the copper-leaf/dokka-json project that Orchid will eventually read. Make all supported languages conform to this common specification
- [ ] 3. Create a common "code doc" plugin in Orchid that reads the abstract model and can generate anything code it needs. It should have a way to register the individual language extensions (potentially using Java Service Locators for Orchid-independence)
- [ ] 4. Deprecate and remove existing code doc plugins, in favor of using the unified and modularized approach above.
New Code Documentation Approach
Currently, each code documentation plugin takes multiple source directories and creates a single "documentation module" per-language. This might cause an issue where code that is separated into multiple modules would be displayed in Orchid as if they were not. Furthermore, code docs from different languges don't necessarily play well together.
Instead of having a separate generator for each language, there will be a single generator. The configuration for that generator specifies a list of "code modules". Each module is given its source language(s), and it will generate the pages for each module in isolation. But it will also create a "module index" and related menu items, etc. You could, for example, create separate modules in your Orchid docs for each Gradle module in the project, where each module is processed separately, even though they have the same source language.
This will also provide a better system for putting code API at subdirectories of your site, while still being able to index and reference external API docs. This will involve publishing a registry of your sites modules in
meta/code-modules.json (or something like that), and at runtime reading an external site's
code-modules.json file, using that to index the pages rendered by each module, and then the page lookups performed when rendering its own site will look in the metadata of those individual modules rather than relying on a specific folder structure of the external site.
Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!
If you have an open-source project that needs docs, are building a new portfolio, or are building any other kind of static site, I want to work with you to get you set up with Orchid! Comment on this post, send me a PM here on Dev.to, or contact me here and I will be with you every step of the way.
And as always, let me know if you start using Orchid so I can feature you in next month's update!