DEV Community: Casey Brooks

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

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 the Showcase to see Orchid in action.

Showcase

Support

Contributors

This project exists thanks to all the people who contribute. To get involved, please see CONTRIBUTING.md

Backers

Thank you to all our backers! 🙏

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

License

Orchid is open-source software licensed under the GNU Lesser General Public License (LGPL-3.0). Please see License.md

Contact

…

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

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 the Showcase to see Orchid in action.

Showcase

Support

Contributors

This project exists thanks to all the people who contribute. To get involved, please see CONTRIBUTING.md

Backers

Thank you to all our backers! 🙏

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

License

Orchid is open-source software licensed under the GNU Lesser General Public License (LGPL-3.0). Please see License.md

Contact

…

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

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 the Showcase to see Orchid in action.

Showcase

Support

Contributors

This project exists thanks to all the people who contribute. To get involved, please see CONTRIBUTING.md

Backers

Thank you to all our backers! 🙏

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

License

Orchid is open-source software licensed under the GNU Lesser General Public License (LGPL-3.0). Please see License.md

Contact

…

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

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 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.

How To Document A Kotlin Project

Casey Brooks ・ Feb 18 '19

#kotlin #documentation #orchid

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

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 the Showcase to see Orchid in action.

Showcase

Support

Contributors

This project exists thanks to all the people who contribute. To get involved, please see CONTRIBUTING.md

Backers

Thank you to all our backers! 🙏

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

License

Orchid is open-source software licensed under the GNU Lesser General Public License (LGPL-3.0). Please see License.md

Contact

…

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!

How To Document A Kotlin Project

Casey Brooks ・ Feb 18 '19 ・ 14 min read

#kotlin #documentation #orchid

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!

Help Me Learn Design Skills!

Casey Brooks — Mon, 25 Feb 2019 16:43:31 +0000

I am typically a mobile/static web developer, and I fully admit that I am not a designer. If you give me a mockup, I can pretty well create a website or Android app to match, but ask me to make the mockup and I don't even know where to start. But I want to be able to do design, even at just a basic level.

Does anyone have any good resources for learning design? I'm wanting to learn Figma, but I've never used these kinds of design tools and I don't even really know what the different buttons do and how to actually use them, so some tutorials on design tools, in general, would be great. And then, of course, articles on the fundamentals of design.

Specifically, my main goal is to create a new landing page for Orchid and revamp its documentation theme, so resources more focused on responsive web and landing pages are appreciated. Thanks!

How To Document A Kotlin Project

Casey Brooks — Mon, 18 Feb 2019 17:28:46 +0000

Documentation is far from being the sexiest thing about software development, but it is certainly necessary. Think back to all the libraries and tools you use every day; they all must have some pretty good documentation, otherwise, you would have never learned how to use them.

So if you're building a library, and you want people to use it, it should also have good documentation. And if that library happens to be written in Kotlin, you're in luck because creating a great documentation website is actually much easier than you might think with the help of a new tool called Orchid.

This tutorial will walk you through how to create a basic documentation site for your Kotlin project with Orchid, including Dokka code docs, a wiki, and changelogs, and get it deployed Github Pages. If you want to jump right into a working project, you can find everything described here in the OrchidTutorials example project.

Getting Started
- App Setup
- Orchid Setup
Adding Content
- Homepage
- Site Info/Theme Configuration
- Wiki
- Changelog
Kotlin Code Docs
- Setting Up The Plugin
- Creating The Menus
Deploy On Github Pages
Conclusion

Getting Started

We'll be using Gradle for this project, but the process will be nearly identical if you prefer Maven.

To start, we'll need a Kotlin project to work with. Ideally, it will be in its own Gradle subproject, such as :app, while the documentation will be in another subproject like :docs. For illustration purposes I am going to quickly set up an example application, but you are free to just follow along using your own library and skip directly to the Orchid Setup section.

App Setup

Starting with a basic Gradle project, we'll need to create our two subprojects. This involves telling Gradle about our projects in settings.gradle, and setting up the Kotlin plugin in the :app project's build.gradle

// settings.gradle
rootProject.name = 'Kotlin Project'

include ':app'

// app/build.gradle
plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.3.21'
    id 'application'
}
repositories {
    jcenter()
}
dependencies {
    compile 'org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.3.21'
}
application {
    mainClassName = 'com.example.MainKt'
}

Now we're ready to start adding and running Kotlin files. For simplicity, we're using the application plugin so we can run a main method in our Kotlin project. We'll set up the application as an Application interface, an ExampleApplication class that implements that interface, and have the main method run that app. Though it is quite simplistic, it will work well enough as an example of the kind of documentation Orchid will generate for it.

So let's get these all set up!

// app/src/main/kotlin/main.kt
package com.example

/**
 * Run the ExampleApplication
 */
fun main() {
    ExampleApplication().run {
        println("Running $name version $version...")
        start("3")
        println("Finished!")
    }
}

/**
 * An Application that can be run with arbitrary arguments.
 */
interface Application {

    /**
     * The name of the application
     */
    val name: String

    /**
     * The current application version
     */
    val version: String

    /**
     * Run this application with the arguments provided
     *
     * @param args the args to configure the application
     */
    fun start(vararg args: String)
}

class ExampleApplication : Application {
    override val version: String = "1.0.0"
    override val name: String = "Example Application"

    override fun start(vararg args: String) {
        for(i in 1..args.first().toInt()) {
            println("$i...")
            Thread.sleep(1000)
        }
    }
}

Now we can run ./gradlew :app:run and Gradle will compile the Kotlin sources and run its main method. You should see the following output:

./gradlew :app:run

> Task :app:run
Running Example Application version 1.0.0...
1...
2...
3...
Finished!

BUILD SUCCESSFUL in 4s
2 actionable tasks: 2 executed

Orchid Setup

Now let's get our project ready to use Orchid. Orchid is a new static site generator, written in Kotlin, which specializes in generating code documentation. It supports Kotlin sources but also has plugins for Java, Groovy, and Swift, which all work very similar to this tutorial.

Orchid runs as a Gradle plugin and is best if it is given its own Gradle subproject. So let's get our settings.gradle setup with a new :docs project, and we'll also set up the docs/build.gradle:

// settings.gradle
rootProject.name = 'Kotlin Project'

include ':app'
include ':docs'

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

// 2. Include Orchid dependencies
dependencies {
    orchidRuntime "io.github.javaeden.orchid:OrchidDocs:0.16.0"
    orchidRuntime "io.github.javaeden.orchid:OrchidKotlindoc:0.16.0"
    orchidRuntime "io.github.javaeden.orchid:OrchidPluginDocs:0.16.0"
}

// 3. Get dependencies from JCenter and Kotlinx Bintray repo
repositories {
    jcenter()
    maven { url = "https://kotlin.bintray.com/kotlinx/" }
}

// 4. Use the 'Editorial' theme, and set the URL it will have on Github Pages
orchid {
    theme = "Editorial"
    baseUrl = "http://username.github.io/project"
    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 wiki and tell it where to find our Kotlin code, but you can run Orchid right now with ./gradlew :docs: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: http://username.github.io/project
-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

[WARN] Warnings:
[WARN] WikiGenerator: 
[WARN]     - Could not find wiki summary page in 'wiki/'


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

// docs/src/orchid/resources/homepage.md
# Kotlin Project

This is a short description of this project.

A common thing to add to the homepage is your project's README, which has things like badges, basic setup instructions, etc. We don't want to have to copy everything from the README to our Homepage file, so let's just tell Orchid to include the README on the homepage for us!

To do this, we will add a Front Matter section to the top of the homepage file, and add the "Readme" Component to the homepage in that Front Matter. If you've previously used Jekyll or another static site generator, Orchid handles Front Matter in the exact same way: YAML between a pair of triple-dashes lines.

// docs/src/orchid/resources/homepage.md
--------
components:
  - type: 'pageContent'
  - type: 'readme'
--------
# Kotlin Project

This is a short description of this project.

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. Here, we've added the readme component, which searches for the README in your project and adds it to the page. We also added 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 components you'll have to add it yourself.

That's about it for the Homepage. But our site is looking a bit boring, and there's some information that the theme would like us to provide. So let's go ahead and configure the theme.

Site Info/Theme Configuration

Orchid handles configuration with a config.yml in the root of your resources. In it, we will add some basic info about our site, and we can also configure our theme, such as changing its colors.

This config file includes some configurations under site, which is common info typically used by any theme you choose, and some theme-specific configuration under Editorial. If you remember, this key is the same value we set as our theme in docs/build.gradle. For the theme, we're changing the site's accent color, and also putting in the Github project for a social link.

# docs/src/orchid/resources/config.yml
site:
  about:
    siteName: Kotlin Project
    siteDescription: This is a short description of this project.
Editorial:
  primaryColor: '#DE9149'
  social:
    github: 'username/project'

But these configuration values didn't just come out of nowhere. If you visit http://localhost:8080/admin while your site is serving locally, you can view Orchid's admin panel. In here you can find all the options available for customization for your theme, for components, and for just about anything else.

Wiki

Now that our site is looking a bit more unique, we can start adding some additional content to help our users learn how to use the project. Orchid's Wiki plugin will help us here, allowing us to create an easily-navigable knowledge base, walking users through everything they need to get going with the project.

This plugin starts with a wiki/summary.md file. In here, we'll add relative links to the subpages in the wiki. Orchid will then create a new page in your site for each entry, and join them all together so that they link from one to the next, in the order declared in the summary.

// docs/src/orchid/resources/wiki/summary.md
- [Installation](installation.md)
- [Basic Configuration](configuration.md)
- [Features](features.md)
  - [Feature One](features/one.md)
  - [Feature Two](features/two.md)
- [Extending](extending.md)

I'll leave the creation of these wiki entries to you. They each work in exactly the same way as the Homepage file and can contain Markdown content and a Front Matter section with any components you wish.

Now, if you visit http://localhost:8080/wiki you'll be able to start navigating your wiki. One of the really nice features of Orchid is the built-in static search. All of your wiki pages support full-text search, to make it easy to look up anything in your site. All the individual pages of the wiki are also linked together with forward and backward links.

The last thing we need to do is start setting up our site menus, and include a link to this wiki. You can do this in config.yml. Change it to look like the following:

# docs/src/orchid/resources/config.yml
site:
  about:
    siteName: Kotlin Project
    siteDescription: This is a short description of this project.

Editorial:
  primaryColor: '#DE9149'
  social:
    github: 'username/project'
  menu:
    - type: 'separator'
      title: 'Wiki'
    - type: 'wiki'

I've added a menu property to the Editorial theme config. Similar to components, a menu contains a list of menu item types which are rendered in order. A single menu item configuration may produce more than one entry in the actual menu as in the wiki item, which adds a link to the sidebar for each page in your wiki.

Changelog

That last piece of content we want to add to our site is a changelog. This way, users can track the changes you've been making to the project, and Orchid can also use this same information to create Releases on Github.

Changelog entries are each set up as a file in your resources changelog directory. Each entry should have a Front Matter section with a version property with the version name (as semantic versioning). So let's go ahead and create some changelog entries, such as changelog/1.0.0.md, and maybe a few others if you want:

// docs/src/orchid/resources/changelog/1.0.0.md
--------
version: '1.0.0'
--------
- Project is now ready for production!

The Changelog plugin does not create a page for the list of changelog entries by default, but we can create a Static Page to display the list of changelog entries. Static pages are markdown files, just like the wiki and homepage files, in the pages directory. We will create a changelog.md file and give it the changelog component to render our versions in order on the page http://localhost:8080/changelog:

// docs/src/orchid/resources/pages/changelog.md
--------
components:
  - type: changelog
--------

Let's also add this to our site menu, so users can easily find the recent changes:

# docs/src/orchid/resources/config.yml
site:
  about:
    siteName: Kotlin Project
    siteDescription: This is a short description of this project.

Editorial:
  primaryColor: '#DE9149'
  social:
    github: 'username/project'
  menu:
    - type: 'separator'
      title: 'Wiki'
    - type: 'wiki'
    - type: 'page'
      itemId: 'Changelog'

Kotlin Code Docs

Setting Up The Plugin

Now we're at a point where we could start documenting our Kotlin sources. First, we need to set up the plugin and point it at our other project with Kotlin source files. The Orchid plugin is already installed as the OrchidKotlindoc dependency in docs/build.gradle, so we just need to update our config.yml.

If we pop back to our admin panel, we can find the config values we need to get going. Specifically, we need to find the "Kotlindoc" Generator menu item in the sidebar. Clicking that shows us the available configuration values that we need to add to config.yml:

This tells us that we can add the following snippet to config.yml, and that's all we need! We'll set sourceDirs to the relative file path from the docs site resources to the app project's Kotlin sources.

# docs/src/orchid/resources/config.yml
kotlindoc:
  sourceDirs:
    - './../../../../app/src/main/kotlin'

Now, Orchid will hook into Dokka to get the info it needs, and then generate pages for each class and package it finds in your source directories (both Java and Kotlin). The fully-qualified name creates nested directories with that same path, so com.example.ExampleApplication will create http://localhost:8080/com/example/ExampleApplication in your site.

Currently, this page doesn't look that great. The default markup is based on Bootstrap, but the theme is not. No worries, however, we can just tell Orchid to add a trimmed-down Bootstrap stylesheet to our Kotlin doc pages!

Let's download this gist to a file named assets/css/orchidKotlindoc.scss. This is a SCSS file, and Orchid will automatically compile it to CSS for us and add it to our Kotlin doc pages with the following snippet in config.yml:

# docs/src/orchid/resources/config.yml
kotlindoc:
  sourceDirs:
    - './../../../../app/src/main/kotlin'
  pages:
    extraCss:
      - 'assets/css/orchidKotlindoc.scss'

There we go, now the pages are looking much better!

We can navigate from this Class page to its package page as well, which looks very similar. And just as the full-text search worked on our wiki pages, it also will find matches within our code comments on these pages as well!

Creating The Menus

We're nearly done setting up our site, there's just one more piece to the puzzle we need: menu links to our Kotlin doc pages! We'll start by adding links to all the classes and packages in our project to the sidebar. This gets added to the same menu list we used earlier for wiki pages in config.yml.

# docs/src/orchid/resources/config.yml
site:
  about:
    siteName: Kotlin Project
    siteDescription: This is a short description of this project.

Editorial:
  primaryColor: '#DE9149'
  social:
    github: 'username/project'
  menu:
    - type: 'separator'
      title: 'Wiki'
    - type: 'wiki'
    - type: 'page'
      itemId: 'Changelog'
    - type: 'separator'
      title: 'API Docs'
    - type: 'kotlindocPackages'
    - type: 'kotlindocClasses'

There's one more menu that is nice to include here as well. Just as the theme has a menu, each page in Orchid can also have its own menu, so that menus may change slightly on different parts of the site, highlighting relevant content. So let's add a menu to all our Kotlin doc pages with links to each method, constructor, etc. on each page. Clicking one of these menu items will link you to the appropriate anchor on the page rather than taking you to a new page.

kotlindoc:
  sourceDirs:
    - './../../../../app/src/main/kotlin'
  pages:
    extraCss:
      - 'assets/css/orchidKotlindoc.scss'
    menu:
      - type: "kotlindocClassLinks"
        includeItems: true

Deploy On Github Pages

Our site is now ready to be deployed! For most projects, Github Pages is a great place to host your docs. All you have to do is push static files to the gh-pages branch of a repository and Github will host it for you.

While many static site generators expect you to commit and push your site to this branch manually, Orchid actually makes it incredibly simple for you by providing you with a simple deployment pipeline. So let's get the Github Pages publication set up. Add the following snippet to config.yml.

# docs/src/orchid/resources/config.yml
services:
  publications:
    stages:
      ghPages:
        branch: gh-pages
        repo: 'project'
        username: 'username'

In addition, we will need to authenticate with Github in order to actually succeed in pushing to that branch. To do that, you need to create a Github Personal Access Token and set it to the githubToken environment variable.

export githubToken=...

Now, instead of running ./gradlew :docs:orchidServe simply run ./gradlew :docs:orchidDeploy -Penv=prod, and Orchid will build your site using your production base URL, and after a successful build push the built site to the gh-pages branch of your repo.

But let's take this just one step further. We always want to make sure that our doc site is up-to-date with the Releases on Github, so no one ever gets misleading or conflicting information. Fortunately, Orchid has another publisher that will create a Github Release based on the latest changelog version! It's just as simple to set up and uses the same githubToken environment variable as the ghPages publisher.

# docs/src/orchid/resources/config.yml
services:
  publications:
    stages:
      ghPages:
        branch: gh-pages
        repo: 'project'
        username: 'username'
      githubReleases:
        repo: 'username/project'

Conclusion

And with all that, our Kotlin project's doc 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 automatically pulls in the README
Wiki that links forward and backward between its entries
A changelog that gets ordered by semantic versioning
Source-code documentation for all your Kotlin and Java sources
Full-text search of your wiki and your KDoc comments
Automatically-generated menu items linking to each page in your wiki and each class and package in your source code.
Easy links to specific methods, properties, etc. on your class and package pages
Deploy the rendered site to Github Pages
Create a Release on Github with the latest changelog version

That's a lot of stuff! And specifically, that's a lot that would normally need a separate tool/build process/3rd-party service for each. In fact, for basic projects Orchid combines all the following tools into its one, unique, integrated platform:

Jekyll
Gitbook
Algolia
Dokka
Custom deployment scripts to publish to Github Pages
Manual Release creation on Github on every release

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, blogs, and much more. Check out the full list of plugins here, or you can even make your own!

Thanks for following along, happy documenting!

Cover photo by Mike Tinnion on Unsplash with modifications by Casey Brooks.