Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

How to Write a Blog

Instructions for creating and publishing a blog with Orchid.


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.

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 {
    orchidRuntime "io.github.javaeden.orchid:OrchidBlog:0.18.0"
    orchidRuntime "io.github.javaeden.orchid:OrchidFutureImperfect: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

[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:

empty Orchid site

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
# Kotlin Project

This is a short description of this project.

Orchid Site with Homepage content

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.

Homepage with Readme contents

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'

Orchid site with some configuration

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.

Orchid Admin Panel Theme Options

Adding Blog Posts

Creating Archives

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.

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!