DEV Community: Casey Brooks

Building Vesper on Ballast: One State Model to Rule Them All

Casey Brooks — Thu, 03 Sep 2026 16:57:21 +0000

As mentioned in the Series Introduction, Ballast is a foundational piece of the architecture of the Vesper app. Ballast is the architecture of the frontend application, and it is the Kotlin-language interface to the server-side schedules and background queue workloads. An understanding of Ballast and the problems it was designed to solve are crucial for understanding why I built Vesper in the way I did.

This post is part of a series on the Vesper Design Diaries, building a Production-Grade KMP App on a Bootstrap Budget. See the Series Introduction for context on the Vesper app and this blog series.

Full disclosure before anything else: I wrote Ballast. I've been building it for several years, and Vesper is the most complete application I've built with it. Take my recommendation with appropriate skepticism — I'm clearly not a neutral party. That said, Vesper is the real test of whether my own ideas hold up under production conditions, and I think they do.

What Ballast Is and Why I Built It

Ballast started out as a KMP MVI framework, essentially a take on the Redux library popular with React. But Ballast takes the general idea of Redux and expands it to leverage some really nice features of the Kotlin language (like sealed interfaces), while allowing more flexibility to the overall "unidirectional data flow" programming model though the use of Coroutines, all without sacrificing any of the safety that this pattern was created for. Ballast is a highly opinionated library that aims to give you a structure for your code that is easily repeatable, yet adaptable for each individual application.

So what does Ballast look like? The short version: every Screen defines a Contract — a sealed interface of Inputs (things that can happen), a State (the current snapshot), and Events (one-shot side effects like navigation or dialogs). In practice with a pure KMP Compose app, Events are not really used (they are much more necessary with working with legacy Android code). But here's what a Contract in Ballast typically looks like, describing the functionality of a Stopwatch:

object StopwatchContract {
    data class State(
        val elapsedSeconds: Int = 0,
        val isRunning: Boolean = false,
    )

    sealed interface Inputs {
        data object Start : Inputs
        data object Stop : Inputs
        data object Reset : Inputs
        data object Tick : Inputs // posted internally when the stopwatch timer is running
    }

    sealed interface Events
}

The Contract is just a statement of the data that can be displayed to the screen (the State), and the Inputs are the actions the UI and background processes dispatch to change the State. An InputHandler processes each Input and returns an updated State or schedules additional work, while a ViewModel wires them together with a CoroutineScope to control its lifetime.

class StopwatchInputHandler : InputHandler<
        StopwatchContract.Inputs,
        StopwatchContract.Events,
        StopwatchContract.State> {

    override suspend fun InputHandlerScope<
            StopwatchContract.Inputs,
            StopwatchContract.Events,
            StopwatchContract.State>.handleInput(
        input: StopwatchContract.Inputs
    ) = when (input) {
        is StopwatchContract.Inputs.Start -> {
            updateState { it.copy(isRunning = true) }
            sideJob("tick") {
                while (true) {
                    delay(1.seconds)
                    postInput(StopwatchContract.Inputs.Tick)
                }
            }
        }
        is StopwatchContract.Inputs.Stop -> {
            updateState { it.copy(isRunning = false) }
            cancelSideJob("tick") /* cancels the running loop */
        }
        is StopwatchContract.Inputs.Reset -> {
            updateState { it.copy(elapsedSeconds = 0, isRunning = false) }
        }
        is StopwatchContract.Inputs.Tick -> {
            updateState { it.copy(elapsedSeconds = elapsedSeconds + 1) }
        }
    }
}

class StopwatchViewModel(
    coroutineScope: CoroutineScope,
) : BasicViewModel<
        StopwatchContract.Inputs,
        StopwatchContract.Events,
        StopwatchContract.State>(
    coroutineScope = coroutineScope,
    config = BallastViewModelConfiguration.Builder()
        .withViewModel(
            inputHandler = StopwatchInputHandler(),
            initialState = StopwatchContract.State(),
            name = "StopwatchViewModel",
        )
        .also { inputStrategy = FifoInputStrategy.typed() }
        .build(),
    eventHandler = eventHandler { },
)

With Compose, it's best to define each screen with two components: one which is fully Stateless that renders content purely based on the current State, and a Stateful version which gets the ViewModel instance via Dependency Injection and coordinates state and inputs with the Stateless version.

// Stateful — acquires the ViewModel and bridges to the stateless component
@Composable
fun StopwatchScreen() {
    val vm = koinViewModel<StopwatchViewModel>()
    val state by vm.observeStates().collectAsState()
    StopwatchScreenContent(state, postInput = { vm.trySend(it) })
}

// Stateless — receives State and a postInput lambda; no ViewModel reference needed
@Composable
fun StopwatchScreenContent(
    state: StopwatchContract.State,
    postInput: (StopwatchContract.Inputs) -> Unit,
) {
    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        Text(text = "${state.elapsedSeconds}s", style = MaterialTheme.typography.displayLarge)
        Row {
            if (state.isRunning) {
                Button(onClick = { postInput(StopwatchContract.Inputs.Stop) }) { Text("Stop") }
            } else {
                Button(onClick = { postInput(StopwatchContract.Inputs.Start) }) { Text("Start") }
            }
            OutlinedButton(onClick = { postInput(StopwatchContract.Inputs.Reset) }) { Text("Reset") }
        }
    }
}

You'll notice that none of the above code requires annotation processors, code generation, or reflection to function. Ballast has none of that. Every contract, handler, and adapter is code I wrote and can navigate to directly in IntelliJ. When something breaks at 2am, I'm not guessing what a generated class is doing — I'm just reading the actual implementation (or nowadays, having Claude read it).

The "no magic" constraint isn't just aesthetics. On Kotlin Multiplatform, code generation support across all targets is still uneven. Reflection is either unavailable or slow on Native. KSP requires additional Gradle boilerplate and longer compile times, and makes it difficult to find, debug, and modify the generated code. Ballast sidesteps those problems entirely by requiring explicit code. You write more boilerplate upfront, but you get a consistent, debuggable, fully-navigable codebase in return, which can be freely modified or extended without requiring changes to the Ballast library itself.

Historically, the boilerplate problem was solved with scaffold tools, but these days, AI agents are so good at following patterns that you really don't even need that. I used Claude Code to build much of Vesper, and I was honestly shocked at how well it was able to follow the Ballast boilerplate without explicit prompting, given that Ballast is a bespoke library without much adoption. As a coworker told me when first getting introduced to Claude, "Claude loves structure". I completely agree, and Ballast's opinionated nature works with that very well.

The Contract Pattern in Practice

A typical screen in Vesper — such as the Submit Prayer screen — defines a contract like this:

object SubmitPrayerScreenContract {
    data class State(
        val prayerText: String = "",
        val isSubmitting: Boolean = false,
        val isError: Boolean = false,
    ) { 
        // many properties can be derived from the state, and it's best to 
        // co-locate that here to keep the logic out of Compose
        val isPrayerValid = prayerText.isNotEmpty()
    }

    sealed interface Inputs {
        data class UpdatePrayerText(val text: String) : Inputs
        data object Submit : Inputs
    }

    sealed interface Events
}

The InputHandler is a pure function that handles Inputs one-at-a-time (though a Coroutine Channel) and provides APIs
to update the state, start "side jobs" (coroutines that run the "background" of the ViewModel), or send Events or
follow-up Inputs.

class SubmitPrayerScreenInputHandler(
    private val submitPrayer: SubmitPrayerUseCase,
    private val router: Router,
) : InputHandler<Inputs, Events, State> {
    override suspend fun InputHandlerScope<Inputs, Events, State>.handleInput(input: Inputs) = when (input) {
        is Inputs.UpdatePrayerText -> {
            updateState { it.copy(prayerText = input.text) }
        }
        is Inputs.Submit -> {
            val currentState = updateStateAndGet { it.copy(isSubmitting = true) }
            try {
                val prayerResult = submitPrayer(currentState.prayerText)
                updateState { it.copy(isSubmitting = false) }
                sideJob {
                    router.sendAndAwaitCompletion(GoToDestination("/prayers/${prayerResult.id}"))
                }
            } catch(e: Exception) {
                updateState { it.copy(isSubmitting = false, isError = true) }
            }
        }
    }
}

Note that unlike Redux, Ballast does not require a strict 1:1 transformation from the Input to a State. Instead, it just carefully guards the internal StateFlow so that a single Input may safely use Coroutines to make several calls in series, updating the state as it goes. It also ensures Inputs are queued up and processed one-at-a-time in the order they were received, making sure there are no race conditions with your InputHandler code.

Since the InputHandler may have dependencies injected via DI, the InputHandler itself must be injected into a ViewModel's constructor, along with a CoroutineScope to define the lifetime of the ViewModel:

class SubmitPrayerScreenViewModel(
    coroutineScope: CoroutineScope,
    inputHandler: SubmitPrayerScreenInputHandler,
    configurationBuilder: BallastViewModelConfiguration.Builder,
) : BasicViewModel<Inputs, Events, State>(
    coroutineScope = coroutineScope,
    config = configurationBuilder
        .withViewModel(inputHandler = inputHandler, initialState = SubmitPrayerScreenContract.State())
        .build(),
)

The coroutine scope comes in from outside. That's the key design choice: whoever provides the scope owns the ViewModel's lifetime. On a screen, that's the navigation backstack entry or the Compose hierarchy (via rememberCoroutineScope()). For app-wide state, it's the Ktor application lifecycle on the server, or an application-scoped scope on mobile. I'll cover the backstack lifetime management in a dedicated post on navigation. I also have a Koin factory { } function which defines a base BallastViewModelConfiguration.Builder, which add cross-cutting Interceptors into all ViewModels, so I get things like automatic logging and a Debugger attached by default.

Application-Wide State

ViewModels don't need to be limited to just the UI layer, though. Vesper uses an additional AppStateViewModel scoped to an application-wide CoroutineScope which holds the state that needs to outlive any individual screen: auth tokens, theme preference, onboarding status, feature flags. This ViewModel uses a @Serializable State class with the saved-state module to persist all changes to multiplatform-settings. Cold launches restore the state from disk rather than starting blank, and the whole application is gated on this state restoration in the Splash Screen, so we can ensure it was correctly restored before attempting to use any of the AppState data.

For an online-first app like Vesper, this pattern acts as a lightweight data layer that sidesteps the need for a full SQLite database. The app's local storage needs are modest — a handful of preference values and session tokens — and a single serialized State covers all of it without a schema, migrations, a query layer, or DAO mapping code. Auth tokens and other sensitive fields are stored using encrypted storage helpers, making the settings store a safe credential store. Because Ballast processes Inputs sequentially, callers can use sendAndAwaitCompletion to post an Input and suspend until it has been fully handled — including until BallastSavedStateInterceptor has flushed the new state to disk. The ViewModel acts as a fast in-memory cache; sendAndAwaitCompletion gives you the guarantee that the cache and the store are in sync when you need it.

The Same Pattern on the Server

Beyond UI and application state, Ballast also powers the server-side background queues (via ballast-queue) and cron-style scheduled jobs (via ballast-scheduler) — the same Contract/InputHandler model, just with Inputs serialized to a Postgres table and retried on failure rather than processed in memory. Navigation is the same story: ballast-navigation drives routing with a URL-based backstack, using the same Contract pattern you saw above. I'll cover all of these topics in their own posts; the point for now is that learning the Contract/InputHandler shape once gives you a mental model that applies across the entire application stack and across various domains, not just UI state.

Why This Matters for Vesper

Vesper is a relatively simple app, and yet still has around 30 screens to manage, along with an application-wide state machine, non-trivial navigation logic, and a lot of complex platform-specific logic needed to bridge everything together. All of this runs within the Ballast system, making all user interactions and state changes predictable and reliable. New developers (or AI agents) know exactly what to look for in any feature: find the Contract, read the Inputs to know what can happen, read the InputHandler to know how those changes get applied.

The consistency also makes testing straightforward. InputHandler implementations have no framework dependencies — they take domain use cases as constructor arguments, which can be stubbed for tests. The State is a plain data class, which allows us to recreate any possible UI state for previews or snapshot tests. There's nothing to mock at the Ballast layer itself. I can verify the full behavioral logic of any screen by constructing its InputHandler, feeding it Inputs, and asserting on the resulting State — no Compose runtime, no Android emulator, no network.

That same legibility extends to AI-assisted development. Because each screen's logic is fully self-contained in a Contract + InputHandler pair, Claude could confidently generate or modify an InputHandler for a screen it had never seen before, just by pattern-matching against the rest of the codebase. The explicit structure that Ballast requires turns out to be exactly the kind of structure that makes a codebase easily understandable to both humans and machines.

I'll be referring back to Ballast throughout this series. The routing system, the server-side queue, and the saved-state adapter are all built on it. Understanding the basic Contract/InputHandler/ViewModel shape is the prerequisite for all of the other posts. You can find more documentation and examples, as well as additional features not used by Vesper such as Undo/Redo support or Firebase integrations, at github.com/copper-leaf/ballast.

Vesper Design Diaries: Building a Production-Grade KMP App on a Bootstrap Budget

Casey Brooks — Thu, 03 Sep 2026 16:25:06 +0000

On September 3rd I launched Vesper, a cross-platform Christian prayer app for Android and iOS, as my entry in the RevenueCat 2026 Shipaton. This is not just a basic app thrown together quickly for this context, though: I have spent months building it and iterating on the features and design, as I am building it as a real production-grade application to bootstrap a business. I'm publishing this series of technical posts as a retrospective look back on how I built it.

A bit of context

I first got the idea for this app and started working on Vesper in early May. The Shipaton happened to coincide with my already-planned release schedule, so I decided to wait a few extra weeks so I could polish things up and document the technical decisions I'd made along the way for the benefit of the Kotlin community. These posts are written after the fact. I'm not live-blogging the build; I'm looking back at what I built and explaining the 'why' behind my decisions.

Vesper was designed heavily around Ballast, a Kotlin Multiplatform state management library I have maintained for many years. Ballast is mostly my personal opinionated structure for building things like per-screen UI state and app navigation, so part of my motivation for this series is showing what Ballast looks like in a real, production-scale application.

But the things I learned building Vesper apply to anyone looking to make a real-world, production-ready application today, whether you choose to use Ballast or not. While these blogs will describe the actual code of Vesper using Ballast, the general knowledge and ways to think about building software capable of handling production workloads are not specific to Ballast.

Who these posts are for

This is an advanced series. I'm not going to walk through setting up a Ktor project from scratch or explain what a coroutine is. What I will do is focus on higher-level architectural decisions and the tradeoffs that come with them — the kind of thinking that goes into building software you actually intend to maintain and grow over many years.

Vesper is not a throwaway pet project. It's the foundation of what I hope can eventually become a real company. That shapes every decision in the codebase.

That said, I want to be honest about the audience for these posts: most of what I describe here is almost certainly over-architected for a simple side project, and quite probably under-powered for an established company with a real engineering team and real infrastructure budget. The constraint I was working under is the one you find at an early-stage pre-launch startup — needing production-stable code without being able to pay for production-grade services. I built a lot of things myself that I could have paid for as a service (email campaigns, feature flags, push notifications, job queues) not just because I couldn't afford those services yet, but also because I don't yet need many of the advanced features those services provide. That context matters when reading these posts.

That said, the ability to tailor these features to exactly my needs without having to compromise on the available features or uptime of another service is a distinct benefit that I will not throw away lightly. I did not build features like job queues or email marketing directly into Vesper just because I want to save money. By building them myself, I am able to evolve the features and functionality along with the product itself in a way that I would not be able to with a SaaS product. It will be slower, for sure, but that's a luxury that I can afford now, and that I believe will continue to serve Vesper well far into the future and lead to an application that is every bit as stable as one built on SaaS products, but at a fraction of the monthly cost.

With Vesper, I find myself working in a space that I have not found to be documented very well, because most content you'll find online is focused on absolute beginners, or large enterprise customers. It's actually pretty hard to bridge the gap between the two, but I hope to be able to give a glimpse into what it looks like working in the space between those two extremes.

Kotlin Multiplatform is not optional here

The entire application is enabled by Kotlin Multiplatform. Vesper in its current form — a single codebase running across Android, iOS, and eventually web, with domain logic, contracts, and data models shared between the Compose frontend and the Ktor backend — could not exist without it. Some of these posts will focus heavily on specific Kotlin language features or KMP-specific patterns. Others will spend more time on the problem itself and less on the Kotlin mechanics. Either way, I'll make sure there's at least one concrete Kotlin snippet in every post so it's grounded in something real.

About the source code

Vesper is a closed-source application. The code I share in these posts is the only direct look at the internals you'll get. That said, nothing in the repo is a genuine trade secret — it's just a mobile app, and a relatively low-risk one at that. Several of the components I built are self-contained enough that I'd happily extract and publish them as open-source libraries if there's enough interest. I'll call those out explicitly as I go, and I'll be providing code snippets where relevant. But because most of the code is currently closed-source, don't expect to be able to copy-and-paste any of these code snippets into your project and expect it to work.

The Roadmap

The series will cover many topics cross the full spectrum of a full-stack Kotlin Multiplatform app, including Compose frontend, Ktor+Exposed backend, and infrastructure.

I will update this list with links and new entries as I publish the posts, so bookmark this page or follow me on Dev.to if you want to follow along!

Building Vesper on Ballast: One State Model to Rule Them All
Designing a User Management system with JWTs, Ktor, and Exposed
Theming and Dynamic Font Loading in Compose
Deep-Linking and Navigation with KMP
Domain-Driven Development - The Secret Weapon for Maintainable Apps
Contract-Based Development for Sharing Code between Compose and Ktor

What Is Vesper?

While I am not writing these blog posts as marketing for the app itself, it may be helpful for you to have a bit of insight into the core functionality of the app.

Vesper is a prayer app and a community of Believers carrying each other's burdens. We gather 2 or 3 to join with Jesus in prayer, building a daily rhythm of intercession together.

Vesper works on a system of matching submitted prayers anonymously to other users ready to pray for them. It's intentionally not a social network as there is no concept of following, liking, or replying to prayers. It's just a place for Christians to ask for prayer in their time of need, and for other Christians to build a stronger habit of prayer by interceding for those requests.

If you're a follower of Jesus and would like to join the community, you can sign up for the mailing list or find links to download the app and join the community at vesperapp.cc.

But regardless of what you believe, I hope this deeper look into what it took to build Vesper will be helpful and a blessing to you!

0.21.0 Released

Casey Brooks — Mon, 01 Jun 2020 18:47:50 +0000

Being stuck at home may not be the most exciting, but it has given me lots of time to fix bugs and make Orchid better for you! This latest release, 0.21.0, includes many bug fixes identified (and sometimes fixed!) by the community, and also boasts some significant internal changes which improve Orchid's overall performance and prepare a major portion of its functionality to be pulled into a standalone library (which you'll absolutely want to check out when it's released).

This is the official Orchid newsletter, the newest and best documentation site generator. 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, milestones, and future plans! Follow along with this series to stay on top of Orchid's newest features, track adoption on Github, and see who's using Orchid!

On Github

The Orchid community is growing larger all the time, and the repo is now at 367 stars!

Orchid also received contributions from Mikko Värri for improvements to sitemaps, and Javier Segovia Córdoba with documentation fixes.

And thank you to everyone else who has been giving Orchid a try, reaching out with questions and feedback, and generally supporting this growing community!

What's New?

Full release notes and a migration guide are available here. Here's a summary of what to expect in 0.21.0:

Experimental sourcedocs are now enabled by default and do not need a CLI flag to use.
Sourcedocs modules can now cross-link between each other for multi-module projects, or those with multiple interlinked sourcesets (like Kotlin MPP).
Collections have become the base unit of organizing groups of pages in Orchid, and there is now a collectionPages menu item to display pages from a collection from any plugin.
Asset management is greatly improved, and support for downloading and inlining CSS and JS assets is now available from config.yml as well as from plugin code.
Diagnostic output across the board is generally improved. Pebble templates are now more descriptive about errors with better line-number tracking (to aid in resolving specific Pebble template issues), and OrchidTest now only shows HTML selectors from the test instead of the entire rendered page.

In Progress

Continued work is underway to support relative URLs (for viewing an Orchid site without needing a local fileserver). In addition, Orchid's resource/file management is a core subsystem that would do well to be a separate library, and work is in progress to move it out of Orchid and into Arcana, it's own library. This library will be Kotlin multiplatform-enabled, bringing Orchid's simple and flexible file-management APIs to Android, iOS, JS, and of course, pure JVM.

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, reach out on Gitter, 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 the next update!

New Snippets plugin, 0.20.0 Released

Casey Brooks — Mon, 30 Mar 2020 17:33:59 +0000

The next major version of Orchid, 0.20.0, is now available! It includes the first introduction of the long-awaited Snippets plugin, as well as a number of smaller quality-of-life improvements throughout. Check out the full release notes here, and stick around for a general update of the development and community around Orchid!

On Github

Orchid is now at 343 stars on Github, and since the last newsletter has received a PR from Bruno Vernay with some improvements to the formatting of blog post filenames.

I also want to give a special thanks to everyone who provided feedback and suggestions for the new Snippets plugin! Both on the proposal issue and on Gitter, your suggestions are what decided the features to include in this first release, and it's my hope that it will provide exactly the solution you're looking for!

And thank you to everyone else who has been giving Orchid a try, reaching out with questions and feedback, and generally supporting this growing community!

What's New?

This latest release is a continuation of the "quality-of-life" improvements that have been suggested by the you and are making Orchid better and easier to use. Some of these changes required breaking the internal API (thus the major version bump to 0.20.0), but this version does not include any deprecations or breaking changes to the public, end-user features. Below are the new features available in 0.19.0:

New Snippets plugin allows you to lookup and embed snippets from code, files, and even external webpages!
The Admin Panel layout got a minor makeover to make it easier to use and more flexible.
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.
Replaces default accordion markup with details/summary HTML5 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, instead of having to have them be statically-determined.
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.
Improvements to base URL management now allow plugins to provide "helpers" for determining the base URL, such as OrchidNetlify detecting when Orchid is running on Netlify's CI platform and using its build environment variables to find the base URL.
OrchidPosts now relaxes slightly the strict filename requirements for post files.

Full release notes and a migration guide are available here.

In Progress

The changes allowing base URLs to be set from config.yml, instead of being a flag from the CLI or build plugins, brings us closer to having relative urls for generated links instead absolute as they are now. Relative URLs don't include a base URL, but instead provide a path from the current page to the linked one, and will make it possible to view an Orchid site directly in the filesystem instead of needing to start an HTTP server to view it.

There is still work to be done on this, but it's now considered a mid- to short-term goal for Orchid instead of a long-term one, and it will be a huge win for those of you using Orchid for documentation. Thank you to everyone who has been asking for this, I hope to be able to provide this feature for you soon!

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!

And as always, let me know if you start using Orchid so I can feature you in the next update!

0.19.0 Released

Casey Brooks — Sun, 23 Feb 2020 23:37:10 +0000

The next major version of Orchid, 0.19.0, is now available! Check out the full release notes here, and stick around for a general update of the development and community around Orchid!

On Github

Orchid is now at 329 stars on Github, and since the last newsletter has received a PR from tomb50 to improve Orchid's Asciidoctor integration. And thank you to everyone else who has been giving Orchid a try, reaching out with questions and feedback, and generally supporting this growing community!

What's New?

Since the release of 0.18.0, I've been able to work on many smaller "quality-of-life" improvements to Orchid that have been suggested by the community. Some of these changes required breaking the internal API (thus the major version bump to 0.19.0), but the last few releases have mainly just been smaller new features and improvements to existing plugins. Below are the new features available in 0.19.0:

Improve Asciidoc formatting. Specifically, other files relative to the source file can now be included.
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.
Adds feedLinks metaComponent to Posts plugin, which adds <link rel='alternate'> tags to page heads, pointing to the generated feed pages.
Images uploaded and referenced from GitLab wikis are now copied over automatically with the rest of the site

Full release notes and a migration guide are available here.

In Progress

Most work over the past month has been refactoring needed to support a better Asciidoctor experience, and generally clean up some of the older parts of the Orchid codebase. This is work that will eventually be extracted to a separate library, so be on the look-out for that!

There is still work to be done with the Asciidoctor integration, but it's getting better all the time, and work on the Snippets plugin will be picking back up soon, too. I've already had some good feedback and suggestions for this feature which I will be taking into account as I build it out, so be sure to leave your thoughts on the appropriate issue, to make this plugin exactly what you need!

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!

And as always, let me know if you start using Orchid so I can feature you in the next update!

January 2020 Orchid Newsletter: Gaining Traction

Casey Brooks — Thu, 23 Jan 2020 16:08:40 +0000

It's so incredible to see this project grow from a tiny seedling to the maturing sprout it is now. Especially since the 0.18.0 release, I've seen more people try out Orchid and adopt it for their documentation sites, and I'm so incredibly grateful for each and every download. But this is only the beginning, Orchid still has lots of growing-up to do, so why don't you come along for the ride and help shape the future of Orchid!

On Github

Orchid has been growing so much since December's 0.18.0 release! Its now at 313 stars and version 0.18.2, with more downloads, new sites, and issues created than ever before! And it's all thanks to this wonderful community of individuals believing in a better way to do documentation, so thank you all!

The holidays were fairly quiet in terms of new releases and contributions, but Tom Beadman helped immensely with improving the asciidoctor integration. A small PR with huge impact for improving the quality-of-life for Asciidoctor fans, which now includes support for include::[] macros!

I also merged work Danilo Pianini had done for improving the YouTube tag to support aspect-ratios instead of fixed sized.

What's New?

Now that 0.18.0 is released, I've been able to work on some smaller features I've been wanting to support for a while. I had to restrain myself from working on them for 0.18.0 to prevent feature-creep, but it's been nice finally getting to add the following features:

The OrchidBible plugin has been broken for some time, as the APIs driving it had been decommissioned. I have removed the previously-broken bible() function, which pre-rendered Bible verses, and replaced it with a new Faithlife Reftagger meta-component, which will automatically create popups for all Bible verses it finds on the page!
Support for Mermaid JS markup has been added to the OrchidDiagrams plugin. As Mermaid is a javascript library, support is added through a meta-component instead of using pre-rendered markup like PlantUML.
The youtube template tag in OrchidWritersBlocks can now display videos of a given aspect-ratio, making them better-suited for responsive designs.
OrchidChangelog now supports single-file changelogs, such as the Keep A Changelog format format.

In Progress

Supporting include macros for Asciidoctor was a huge step forward, but there's still work to be done to improve that integration, and you can expect more Asciidoctor improvements in the coming weeks, with image::[] being the next target.

In addition to a few more quality-of-life improvements planned for the near-future, I've begun work on a new OrchidSnippets plugin! More details will come in a future post, but I'd love to get your feedback and suggestions for its implementation and usage in this issue on GitHub!

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!

And as always, let me know if you start using Orchid so I can feature you in the next update!

Make a Personal Blog with Orchid

Casey Brooks — Thu, 12 Dec 2019 16:53:26 +0000

Orchid was created to create amazing project documentation sites, but it is by no means limited to documentation. Orchid is equally good at producing blogs for your portfolio site, or even for adding a newsletter to your docs to further
engage with your users!

This tutorial will walk you through how to create a blog, complete with archives for all your posts, and get it deployed to Netlify. If you want to jump right into a working project, you can find everything described here in the OrchidTutorials example project.

orchidhq / OrchidTutorials

A collection of tutorial projects to help you learn how to use Orchid

Orchid Tutorials

This repo contains the projects used in the official Orchid tutorials. Each project top-level directory here is its own project, and can be run by navigating into that project and running the appropriate commands as described in the Orchid tutorials.

View on GitHub

Alternatively, you can simply click the "Deploy to Netlify" button below to automatically clone, build, and deploy the OrchidStarter repo to the Netlify CDN. Most of what is in this tutorial is also included in that site, so you can follow along with this tutorial using the starter repo as well.

This tutorial was originally posted on https://orchid.run. Visit the original tutorial for the most up-to-date version.

Getting Started

We'll be using Gradle for this project, and Orchid runs as a Gradle plugin. So let's get our settings.gradle and we'll also set up the build.gradle:

// settings.gradle
rootProject.name = 'My Awesome Blog'

// build.gradle
// 1. Apply Orchid plugin
plugins {
    id "com.eden.orchidPlugin" version "0.18.0"
}

// 2. Include Orchid dependencies
dependencies {
    orchidCompile "io.github.javaeden.orchid:OrchidBlog:0.18.0"
    orchidCompile "io.github.javaeden.orchid:OrchidFutureImperfect:0.18.0"
    orchidCompile "io.github.javaeden.orchid:OrchidSearch:0.18.0"
    orchidCompile "io.github.javaeden.orchid:OrchidPluginDocs:0.18.0"
}

// 3. Get dependencies from JCenter
repositories {
    jcenter()
}

// 4. Use the 'FutureImperfect' theme, and set the URL it will have on Github Pages
orchid {
    theme = "FutureImperfect"
    baseUrl = "https://project.netlify.com"
    version = "1.0.0"
}

This is all that's required to run your Orchid site! There are still a few things we need to do to set up the blog, but you can run Orchid right now with ./gradlew orchidServe and view the site on http://localhost:8080. It should give you an output like the following:

./gradlew :docs:orchidServe

> Task :docs:orchidServe
Using the following modules: 
--------------------
 * com.eden.orchid.StandardModule

Auto-loaded modules: 
--------------------
 * com.eden.orchid.editorial.EditorialModule
 * com.eden.orchid.impl.compilers.markdown.FlexmarkModule
 * com.eden.orchid.impl.compilers.pebble.PebbleModule
 * com.eden.orchid.kotlindoc.KotlindocModule
 * com.eden.orchid.pages.PagesModule
 * com.eden.orchid.search.SearchModule
 * com.eden.orchid.wiki.WikiModule

Flag values: 
--------------------
-adminTheme: Default
-baseUrl: https://project.netlify.com
-defaultTemplateExtension: peb
-dest: ...
-dryDeploy: false
-environment: debug
-logLevel: VERBOSE
-port: 8080
-src: ...
-task: serve
-theme: Editorial
-version: 1.0.0

[INFO] Orchid: Running Orchid version 0.16.0, site version unspecified in debug environment
[INFO] OrchidWebserver: Webserver Running at http://localhost:8080
[INFO] OrchidWebsocket: Websocket running at http://localhost:8081/
[INFO] TaskServiceImpl: Build Starting...
[INFO] GeneratorServiceImpl: Indexing [10000: assets]
[INFO] GeneratorServiceImpl: Indexing [1000: home]
[INFO] GeneratorServiceImpl: Indexing [1000: kotlindoc]
[INFO] GeneratorServiceImpl: Indexing [1000: pages]
[INFO] GeneratorServiceImpl: Indexing [1000: wiki]
[INFO] GeneratorServiceImpl: Indexing [11: sitemap]
[INFO] GeneratorServiceImpl: Indexing [10: indices]
[INFO] GeneratorServiceImpl: Generating [10000: assets]
[INFO] GeneratorServiceImpl: Generating [1000: home]
[INFO] GeneratorServiceImpl: Generating [1000: kotlindoc]
[INFO] GeneratorServiceImpl: Generating [1000: pages]
[INFO] GeneratorServiceImpl: Generating [1000: wiki]
[INFO] GeneratorServiceImpl: Generating [11: sitemap]
[INFO] GeneratorServiceImpl: Generating [10: indices]

Build Metrics:
┌───────┬────────────┬───────────────┬─────────────────┬───────────────────────────┬─────────────────────────────┐
│       │ Page Count │ Indexing Time │ Generation Time │ Mean Page Generation Time │ Median Page Generation Time │
├───────┼────────────┼───────────────┼─────────────────┼───────────────────────────┼─────────────────────────────┤
│  home │     1      │     54ms      │      481ms      │           472ms           │            472ms            │
├───────┼────────────┼───────────────┼─────────────────┼───────────────────────────┼─────────────────────────────┤
│ TOTAL │          1 │      3s 496ms │           520ms │                     472ms │                       472ms │
└───────┴────────────┴───────────────┴─────────────────┴───────────────────────────┴─────────────────────────────┘

Build Complete
Generated 1 page in 4s 18ms


Webserver Running at http://localhost:8080
Hit [CTRL-C] to stop the server and quit Orchid

You will also see the basic site served on localhost:8080, which looks like:

But let's move on to the next step: adding content to the site!

Adding Content

Homepage

The first thing anyone will see when landing on your site is your Homepage. Orchid creates this page based on a homepage.md file in the root of your site's resources, which are located by default in src/orchid/resources. Let's start by creating this file and adding a short description of our project to it.

// docs/src/orchid/resources/homepage.md
# My Blog

This is a short description of this blog.

A common thing to add to your blog homepage is a list of your latest blog posts. But before we add that, we'll need to write some blog posts first.

Blog Posts

Blog posts are Markdown files in your posts/ directory, where each file is a separate blog post. The filename of the post must be in the format of YYYY-MM-DD-[post-title].md, with the publication date and the "slug" of the post which will be its path in its URL.

So let's add a few posts, such as posts/2019-01-01-post-one.md, posts/2019-02-01-post-two.md, and posts/2019-03-01-post-three.md. The contents of each file should start with a Front Matter section, where you can specify the post's title, its tags, and other metadata, and the actual post content after that. Front Matter is a block of YAML between pairs of triple-dashed lines.

# posts/2019-01-01-post-one.md
---
title: Example Post 1
featuredImage: assets/media/pic01.jpg
tags:
    - one
    - two
---

Example Post 1

You'll now have a blog post at http://localhost:8080/2019/1/1/post-one that looks like the following;

Now that we have some blog posts set up, we can go back and add the latest posts to our homepage. We can do by adding a component to the homepage's Front Matter, configured to display the latest posts. Orchid's Components are just a list of "blocks" which are rendered to the page in order. There are many different types of components, and different plugins can add their own. An example is the recentPosts component from the OrchidPosts plugin. We can also add the pageContent component, which adds the Markdown content of the homepage.md. If you don't define any components this one is added automatically, but if you use any additional components you'll have to add it yourself.

# homepage.md
---
components:
  - type: pageContent
  - type: recentPosts
    limit: 4
    noWrapper: true
    template:
      - 'includes/postPreview_large'
---
# My Blog

This is a short description of this blog.

Creating Archives

Post Archive

Now, while it is nice to show the most recent posts on your site's homepage, if you've got more than a couple posts you simply can't show a complete archive on the homepage. Instead, we can use the OrchidTaxonomies plugin to generate proper archives.

Orchid is designed around a concept of "collections" of pages. When we set up the blog posts, Orchid also created a posts collection. We can tell the Taxonomies plugin to generate an archive of any of our collections from any plugin, making it simple to create any archives we may need.

Configuring archives is done through a config.yml file in our site resources. This is the main entry-point to configuring anything in our site. The following snippet will set up a collection archive for all our blog posts.

# docs/src/orchid/resources/config.yml
taxonomies:
  collectionArchives:
    - collectionType: 'posts'
      collectionId: 'blog'

Now, if we visit http://localhost:8080/blog, we will see a listing of all our blog posts. As our blog grows, this archive will automatically become paginated, keeping any single page from growing too large.

You may wish to create archives for other collections as well. If you visit http://localhost:8080/admin while your site is serving locally, you can view Orchid's admin panel where we can see a list of all the collections that have been set up for us.

Tag Archives

But the full listing of posts may not be the only kind of archives we want! Most blogs will also contain listings of posts by tag (remember, we provided a list of tags to our posts earlier!). Orchid did not create a collection for these tagged pages, but that doesn't mean we can't create an archive for them too! The Taxonomies plugin is able to generate any kind of arbitrary archive, based on the metadata attached to each post. These are called taxonomy archives, because you get to create any kind of taxonomy (or labelling) you need.

Configuration of a taxonomy archive is similar to a collection archive, but instead of giving it the values for a collection, we tell it a property to look for in our posts' Front Matter, such as tags:

taxonomies:
  collectionArchives:
    - collectionType: 'posts'
      collectionId: 'blog'
  taxonomies:
    - key: tags
      single: false
      orderBy:
        - entryCount

This will now go through all our posts, find any that have a tags property in its Front Matter, and add it to that archive. And this will actually create two archives for each "taxonomy": one listing all the pages with each tag (a term archive), and another archive simply listing all the tags that it found (a taxonomy archive).

http://localhost:8080/tags

http://localhost:8080/tags/one

Site Info/Theme Configuration

With the skeleton of our site content set up, it's time to make some customizations to the theme and add additional info about your site, such as its name and the author of your posts. These can be added to config.yml, just like how we configured the archives.

# docs/src/orchid/resources/config.yml
site:
  about:
    siteName: My Blog
    siteDescription: This is a short description of this blog.
    avatar: 'http://lorempixel.com/320/320/city/'
theme:
  social:
    github: 'username/project'

But these configuration values didn't just come out of nowhere. Going back to the admin panel, you can find all the options available for customization for your theme, for components, and for just about anything else.

There's a final bit of info that we should need to config.yml before finishing: setting the author for all our posts.

You would normally add the necessary configuration to each post's Front Matter, but it is really difficult, time-consuming, and error-prone to copy this data to each post file. Instead, Orchid has Archetypes which allow you to set that configuration once in config.yml and have it shared amongst a bunch of pages just as if it were added to the Front Matter of each one.

For adding configuration values to all post pages, use posts.postPages in the config.yml. We'll add an author to the blog by adding an item to the posts.authors list, and using the archetype we'll set the author for each page to the one you just set up:

# docs/src/orchid/resources/config.yml
posts:
  authors:
    - name: 'Author One'
      avatar: 'http://lorempixel.com/320/320/animals/'
      email: 'email@domain.tld'
  postPages:
    author: 'Author One'

Deploy On Netlify

Our site is now ready to be deployed! For blogs and personal sites, you really can't go wrong with Netlify as your site host. It offers everything you could want for both small and large sites, such as purchasing custom domains, form handling, and automated site deploys. While Orchid has its own Netlify publisher for advanced use cases, it's far simpler to use Netlify as intended.

All you need to do is create an account at https://www.netlify.com/, add a netlify.toml file to the root of your repo with the following content, and push to GitHub.

[build]
  base    = ""
  publish = "build/docs/orchid"
  command = "./gradlew orchidBuild -Penv=prod"

Now, once you've connected that repo to Netlify, they will take care of the rest! Of course, this is just the minimum needed to deploy, and I'd encourage you to also check out their full documentation for more help building and deploying your Orchid site on Netlify.

Conclusion

And with all that, our blog site is finished! Now it may have seemed like a ton of work getting all that setup, but let's recall all the features included in this site:

A homepage that displays our latest blog posts
A full, paginated archive of all blog posts
A listing of all tags in your blog
An archive for all the pages with each tag
Ability to set the author for each post
Ability to easily change the configurations for all your blog posts from a single location, instead of copying data to each post

And everything outlined in this tutorial is really just a sampling of the full functionality available in Orchid! Orchid has other plugins for different source code documentation, presentations, wikis, and much more. Check out the full list of plugins here, or you can even make your own!

Thanks for following along, happy blogging!

Orchid 0.18.0, The New Face of Orchid

Casey Brooks — Tue, 10 Dec 2019 16:12:46 +0000

It's. Finally. Here. I've been working on and teasing a new major version of Orchid for several months, and it's finally available! This release represents a major step in the maturity of Orchid, coming alongside the move to a new GitHub organization, a completely redesigned website, and a brand new logo!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

Orchid 0.X.X versions are published to JCenter at artifact coordinates like io.github.javaeden.orchid:OrchidCore:0.21.1 or io.github.javaeden.orchid:OrchidWiki:0.21.1. JCenter is deprecated, and once Orchid 1.0.0 is published, so will all 0.X.X versions.

Starting with version 1.0.0, Orchid will be published to MavenCentral under new artifact coordinates, like io.github.copper-leaf.orchid:orchid-core:1.0.0 or io.github.copper-leaf.orchid:orchid-wiki-feature:1.0.0.

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 278 stars on Github, thank you so much for all the support!

Since the last update, Orchid has had several contributions, especially during Hacktoberfest, so a special thanks goes out to the following individuals for their help improving this project:

spind42 - Fixed an issue running Orchid from Maven
Jean-Michel Fayard - Added a readme badge for CodeTriage
Steve S - Added a new Spotify tag to the OrchidWritersBlocks plugin
Steve Waldman - Wrote a plugin to run Orchid from SBT!

What's New?

The long-awaited version 0.18.0 has finally arrived!

This release includes a major cleanup to Orchid's internal APIs, which will help make better plugins moving forward, but most importantly introduces the new, completely rewritten code documentation system based on Kodiak. The new system improves consistency of generated docs among all languages and enables multi-module documentation. It also paves the way to make it significantly easier to develop integrations for other languages, so let me know which languages you would like to see supported by Orchid!

Be sure to check out the Changelog for the full list of changes, and the Migration Guide for help updating to this new version.

In addition, some of you may have noticed a few changes around the Orchid ecosystem! The Orchid repo has been moved to @orchidhq on Github, and we have a completely redesigned documentation site and new logos. Together with the 0.18.0 release, this marks the biggest change in the development and ecosystem of Orchid to help cement it is as the single-best tool for producing documentation websites.

You can help spread the word about this major milestone by sharing https://orchid.run and tagging @OrchidSSG on Twitter!

Who's Using Orchid?

I periodically search GitHub to find new projects getting set up with Orchid. Here are a couple great examples of projects being documented with Orchid:

For more examples of sites using Orchid, head on over to our new Showcase, and feel free to reach out or submit a PR to add your site to the showcase as well!

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!

And as always, let me know if you start using Orchid so I can feature you in the next update!

Orchid Newsletter: Summer Recap

Casey Brooks — Wed, 11 Sep 2019 17:11:21 +0000

Sorry for the absence, it's been a very busy summer for me! Lots of stuff going on both for me and for Orchid, so stick around to see what's coming up!

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!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 233 stars on Github, thank you so much for all the support! And a special thanks goes to the following individuals who submitted pull requests to Orchid!

I've also been preparing for Hacktoberfest, which is coming up in less than a month. I've curated a bunch of new issues labeled for first-time contributors, how about getting a head-start on Hacktoberfest and helping out with some of these issues? 😎 Feel free to hold off on your PR until Hacktoberfest officially begins, just comment on the issue so others know what you're working on.

What's New?

Orchid is now at version 0.17.4. 0.17.0, which came out at the end of May, was a really big update and included a handful of new "integrations" projects. These integrations make it easy to create wikis from Github and Gitlab wikis, and to publish your site to Gitlab Pages and Bitbucket Cloud (in addition to the already-supported Github and Netlify publishers).

In Progress

Y'all. Some big things are just up the road for Orchid. Really big. Like, Texas-sized big. I'm talking about:

A completely redesigned documentation site (you can preview it here, I'd greatly appreciate any feedback on it!)
Mutli-module code documentation
Completely decoupling code documentation from Orchid with Kodiak, to vastly simplify the process of supporting new languages and ensure consistency of usage across all languages
Some much-needed refactoring of core Orchid functionality
A new framework for automated testing of Orchid plugins and themes
Migrating to GitHub Actions for continuous releases

All this will be coming in the upcoming 0.18.0 release. While I don't want to put a date on this release (I don't want to release it until it's 100% ready-to-go), I can say that I'm nearly code-complete with the changes I wanted to add. From here, it's mostly just adding the finishing touches to the new site, documenting the new functionality, and testing everything thoroughly.

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!

And as always, let me know if you start using Orchid so I can feature you in next month's update!

Orchid Newsletter: In Bloom

Casey Brooks — Tue, 07 May 2019 21:08:12 +0000

April has just ended, which means summer is coming! April in Texas means lots of rain, the first hot days of summer, and bluebonnets in bloom along every highway. It's also been a relatively slow month for Orchid, but lots of really cool stuff is just about to bloom here too!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 196 stars on Github. Just 4 more stars until the next major milestone of 200, will you help us get there?

What's New?

Orchid is now at version 0.16.10, with a few minor updates released throughout the month.

Orchid no longer includes any Lombok code, for a more stable codebase and a better roadmap for converting the remaining Java code to Kotlin.
Relative base URLs are now supported
Adds baseUrl and homepageUrl filters to be more tolerant when formatting ad-hoc URLs
Updates to Pebble 3.0.9, which includes the embed tag I contributed to that project. This will go a long way in improving theme development in Orchid
Improved error-handling

In Progress

I've been pretty busy in April and haven't had as much time to dedicate to Orchid development. One of my other hobbies is woodworking, and I've been taking some time in this nice weather to build a new coffee table as a late Christmas present to my wife. I'm pretty proud of my work on it, it's teaching me some skills that are valuable in software development, and you can keep an eye out for a blog post on that! Here's my progress on this build so far:

But despite that, I'm also making some great progress toward the next major release, 0.17.0! This will be a significant refactoring and improvement of the wiki and deployment features in Orchid to allow better integrations with all the major Git hosting platforms and pave the way for easier integration of similar features in the future.

It's a pretty significant change and is taking a lot of work, but I have a goal of finally getting it out this month! Here's the full list of features that you can expect in this release:

Netlify deploys optimized for really large sites, and able to upload serverless Functions
Deploy site to GitHub, Bitbucket, GitLab, or Azure DevOps (currently, only GitHub is supported)
Import wiki content directly from GitHub Wikis

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!

Orchid Newsletter: March Madness

Casey Brooks — Wed, 03 Apr 2019 15:56:32 +0000

I love watching basketball, which makes March one of the best months of the year as the NCAA National Championship, March Madness, takes place. My top pick, Michigan State, has already defeated Duke and is well on their way to becoming the National Champions!

It has also been quite a "mad" month for Orchid too, with lots of big changes in progress. From being able to publish your site to Gitlab and Bitbucket, to integration with Github Wikis, and a re-theming of the documentation site all underway, it's safe to say that I've been quite busy!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 175 stars on Github. And this month, in particular, I have been absolutely blown away at the growth on Github. With 4 pull requests by 3 contributors, numerous issues opened and questions asked across Github, Twitter, and Gitter, and more than FOUR TIMES as many downloads on Bintray this month as last month, Orchid is seeing unprecedented growth that I could never have imagined.

Thank you all so much, I certainly could not keep working this hard without your incredible support! But these successes are entirely because of you, and I love to give credit where it is due, so let's drill into this a bit deeper.

Contributions

@alejandrohdezma helped out to fix a bug using the wrong FontAwesome icon (#239)
@ Sumo99 got rid of the last of Lombok, paving the way for a pure-Kotlin future! They also helped remove Google Plus social links now that the service is officially dea. (#243 and #249)
@ dkowis fixed a broken documentation link (#252)

4x Downloads Increase

The 31-day period ending February 28th saw a bit shy of 700 downloads.

The stats show that downloads really started to take off around the end of the month, which is when I published the tutorial on how to use Orchid to document a Kotlin project. I would highly recommend you check it out if you haven't already.

Casey Brooks

Feb 18 '19

How To Document A Kotlin Project

#kotlin #documentation #orchid

14 min read

Meanwhile, The 31-day period ending March 31st saw more than 2600 downloads! And questions from y'all on how to use it have increased to match, and I'm so excited to be able to help solve your problems with Orchid!

All of these statistics are freely available on Bintray, go here to check it out for yourself.

What's New?

Orchid is currently at version 0.16.7. There have been no major changes since last month, mostly just a series of bugfixes on the Copper theme and minor usability improvements.

Coming Soon

New Docs

Orchid's docs are getting a reboot! When I started work on Orchid, Bootstrap was the only CSS framework I knew of. I had no idea there were so many great options out there, and ultimately I have come to really enjoy Bulma for its simplicity and flexibility.

And so, I've been building the "Copper" theme, based on Bulma, to serve as the home for all of Orchid's own documentation, and also of its supplemental libraries. Here's a preview:

Also coming with the new theme will be a major overhaul in the content on the docs site, as I continue to iterate upon the docs and figure out the best way to present the information to you.

More Integrations

From the very beginning, Orchid was created to be infinitely flexible, able to work with a wide variety of different systems and content structures, but until now it has been fairly closely tied to just Netlify and GitHub. I myself regularly use Microsft Azure and BitBucket at work and want to use Orchid in those places, and I can imagine y'all do as well.

So work is currently under way to make it easier to integrate Orchid into those different Git platforms, so you do not need to change your current processes to fully utilize Orchid's power! Soon, you'll be able to use the native Wikis on Github, Bitbucket, Gitlab, and Azure DevOps as a headless CMS, and you'll also be able to deploy directly to their static hosting platforms and create releases!

Get Involved

You don't have to be an expert in Java, Kotlin, Orchid, or anything else to help out the Orchid project. There are a number of ways you can contribute right now:

fixing typos and improving the clarity of documentation articles
converting Java classes to Kotlin

However, I am currently looking for more skilled help with a couple specific areas:

I'm looking for people who currently use the features of the git platforms I'm imtegrating with, to help build their integrations:
- GitLab
  - Wiki adapter
  - GitLab Pages Publisher
- Bitbucket
  - Wiki adapter
  - Bitbucket Cloud Publisher
- Azure DevOps
  - Wiki adapter

I would also love the help of a designer to make a really great home page and a new logo for Orchid.

Please reach out to me if you're interested in contributing to the project for any of these specific issues, I (and the whole community!) would really appreciate it!

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!

Orchid Newsletter: One Love

Casey Brooks — Sat, 02 Mar 2019 20:39:07 +0000

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.

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

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!

In The Media

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!

Casey Brooks

Feb 18 '19

How To Document A Kotlin Project

#kotlin #documentation #orchid

14 min read

What's New?

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!

New theme: Copper

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.

For examples of Orchid sites using this new theme, checkout caseyjbrooks.com or the Trellis docs and JSON Documentation Formatters docs.

New bundle: Orchid Docs

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
OrchidSyntaxHighlighter: Your choice of either server-side or Javascript-based highlighting

New plugin: Groovydoc

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.

Coming Soon

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.

Modularize and unify code documentation plugins #232

cjbrooks12 posted on Feb 22, 2019

This is the beginning of a major reworking of how Orchid handles code documentation. These changes are mostly structural, and I expect only minor changes to be needed by end-users when it is complete.

Abstract

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.

Requirements

[x] 1. Get all languages currently supported by Orchid moved to the model used in the copper-leaf/kodiak project
[X] 1.1. Java
[X] 1.2. Kotlin
[X] 1.3. Groovy
[x] 1.4. Swift
[x] 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
[x] 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)
[x] 3.1. Generate doc pages similar to existing plugins (but namespaced)
[x] 3.2. Allow multiple modules for each source type, each with multiple source dirs
[x] 3.3. Landing pages with README page content for each module
[x] 3.4. Menu items
[x] 3.4.1. Page links (link to IDs on a single page)
[x] 3.4.2. Module pages (link to subpages of a single module)
[x] 3.4.3. Modules (link to homepages of each module)
[x] 3.5. Collections
[x] 3.5.1. Pages by node-kind for each module
[x] 3.5.2. All doc pages each module
[x] 3.5.3. Landing pages for all modules
[x] 4. Deprecate and remove existing code doc plugins, in favor of using the unified and modularized approach above.
[x] 4.1. Deprecate existing plugins, but keep around for 0.18.0 release
[ ] 4.2. Completely remove existing plugins in 0.19.0 release

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.

View on GitHub

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!