A beautiful and truly unique documentation engine and static site generator.
Permalink
Failed to load latest commit information.
.github Updates readme to include Kscript quick-start Oct 25, 2018
OrchidCore Adds asset template function and implements basic thumbnail resizing … Nov 12, 2018
buildSrc Fixes issues starting Orchid when there are params that are null Oct 31, 2018
bundles Cleaned up structure of Gradle scripts, fixed compiler warnings May 30, 2018
gradle Initial setup of generating PDFs from Wiki sections Nov 11, 2018
languageExtensions Attempts to hack my way into using jar resources during tests where t… Oct 21, 2018
plugins Adds asset template function and implements basic thumbnail resizing … Nov 12, 2018
themes Renames menu classes Nov 1, 2018
.gitignore Dynamically set the version for Maven plugin releases Oct 24, 2018
.travis.yml Dynamically set the version for Maven plugin releases Oct 24, 2018
License.md Changes license from MIT to LGPL Jun 2, 2017
README.md Adds Azure DevOps build status badge to README Nov 10, 2018
appveyor.yml Converts tasks and commands to Kotlin in core project. Gets basic wor… Aug 30, 2018
build.gradle Updates dependency versions Oct 20, 2018
gradle.properties Fixes Gradle build Dec 21, 2016
gradlew Makes several minor code and documentation updates Nov 28, 2017
gradlew.bat adds for testing Orchid on Windows May 28, 2017
netlify.toml Updates Netlify build command Aug 13, 2018
semantic-build-versioning.gradle Starts to set up semantic versioning for CI Dec 29, 2017
settings.gradle Converts tasks and commands to Kotlin in core project. Gets basic wor… Aug 30, 2018

README.md

Orchid

Build Status Linux and Mac Build Status Windows Build status Current Version License: LGPL-3.0 Codacy Grade Codacy Coverage Gitter chat

A beautiful and truly unique documentation engine and static site generator.

Example Orchid site

Orchid is a brand-new, general-purpose static site generator for Java and Kotlin, with a focus on extensibility and aimed at developers looking to improve their technical documentation. Orchid was born out of a desire for better-looking Javadocs and frustration with how difficult is it to manage large Jekyll sites and keep it up-to-date with your code.

Orchid supports a variety of plugins, including a wiki, static pages, blogs, and much more. It aims to have high compatibility with many of the existing static site generators, such as Jekyll, Gitbook, and Hugo, so that migration to Orchid is painless. And if you can't find a plugin to do what you need, Orchid provides an intuitive way to add your own private plugins and a rich API so you can make your site as beautiful and unique as an Orchid.

Features

  • Plugin-driven architecture
  • Multi-theme support
  • Admin interface to manage your content and gain deep insights into your build
  • Link to other Orchid sites
  • Powerful and flexible indexing, unique to Orchid
  • Full-text static search
  • Component-based content management
  • Integrated deployment pipeline
  • Fully replaces Jekyll, Hugo, Gitbook, Javadocs, and more!

View the full documentation or see the quick-start below.

Table of Contents

  1. Quick Start
    1. Gradle
    2. Maven
    3. KScript
  2. Example Orchid Sites
  3. Development Progress
    1. Core Packages
    2. Themes
    3. Plugins
  4. License
  5. Contributing
  6. Contact

Quick Start

Orchid integrates with any new or existing Gradle/Maven project. The simplest way to get started is to deploy the starter repo directly to Netlify. Just click the button below to automatically clone this repo and deploy it to Netlify. The starter repo includes the Netlify CMS, so you will be up and publishing content as soon as possible. You will need to set the Github user/repo in src/orchid/resources/config.yml, but the rest of the CMS config is automatically generated based on your current Orchid plugins and configurations.

Deploy to Netlify

To run Orchid locally, the only system dependency necessary is a valid Java 8 JDK. Orchid can be integrated with any new or existing Gradle or Maven project or bootstrapped manually in any JVM-based scriptlet (such as kscript). To get started, pick a Bundle (OrchidAll or OrchidBlog) or manually choose your desired Orchid plugins. You may pick a bundle to start with and add any number of plugins afterward, both official and unofficial.

Configuring a Gradle project

To use Orchid from a Gradle project, setup your project's build.gradle file like so:

plugins {
    // Add the official Orchid Gradle plugin so you can use Orchid with the custom DSL   
    id "com.eden.orchidPlugin" version "{version}"
}

repositories {
    // Orchid uses dependencies from both Jcenter and Jitpack, so both must be included. jcenter also includes 
    // everything available from MavenCentral, while Jitpack makes accessible any Github project.
    jcenter()
    maven { url "https://kotlin.bintray.com/kotlinx" }
    maven { url 'https://dl.bintray.com/javaeden/Orchid/' }
    maven { url 'https://dl.bintray.com/javaeden/Eden/' }
    maven { url 'https://jitpack.io' }
}

dependencies {
    // Add an Orchid Bundle. OrchidAll comes with all official themes included.
    // You must include a theme separately when using the OrchidBlog bundle.
    // Any additional plugins may be added as dependencies here as well.
    orchidRuntime 'io.github.javaeden.orchid:OrchidAll:{version}'
}

orchid {
    // Theme is required
    theme   = "{theme}"
    
    // The following properties are optional
    version = "${project.version}"
    baseUrl = "{baseUrl}"                         // a baseUrl prepended to all generated links. Defaults to '/'
    srcDir  = "path/to/new/source/directory"      // defaults to 'src/orchid/resources'
    destDir = "path/to/new/destination/directory" // defaults to 'build/docs/orchid'
    runTask = "build"                             // specify a task to run with 'gradle orchidRun'
}

You can now run Orchid in the following ways:

  1. ./gradlew orchidRun - Runs an Orchid task. The runTask should be specified in build.gradle or passed as a Gradle project property (-PorchidRunTask=build). The task help will show a list of all tasks that can be run given the plugins currently installed.
  2. ./gradlew orchidBuild - Runs the Orchid build task a single time then exits. The resulting Orchid site will be in build/docs/orchid unless the output directory has been changed. You can then view the site by starting any HTTP file server in the root of the output directory, or deploy this folder directly to your webserver.
  3. ./gradlew orchidWatch - Runs the Orchid build task a single time, then begins watching the source directory for changes. Anytime a file is changes, the build will run again, and the resulting Orchid site will be in build/docs/orchid unless the output directory has been changed.
  4. ./gradlew orchidServe - Sets up a development server and watches files for changes. The site can be viewed at localhost:8080 (or the closest available port).
  5. ./gradlew orchidDeploy - Runs the orchid build, then deploys it using Orchid's deployment pipeline You can create and run your own deployment scripts, create a release on Github from changelogs, or publish the site directly to Github Pages or Netlify.

On windows, all the above commands need to be run with gradlew instead of ./gradlew.

The Orchid Gradle plugin adds a new configuration and content root to your project, in the src/orchid directory (you may have to create this folder yourself). All your site content sits in src/orchid/resources, and any additional classes you'd like to include as a private plugin can be placed in src/orchid/java.

Configuring a Maven project

To use Orchid from a Maven project, setup your project's pom.xml file like so:

<project>
    ...
    
    <properties>
        <orchid.version>{version}</orchid.version>
    </properties>

    <build>
        <plugins>
            <!-- Add the official Orchid Gradle plugin so you can use Orchid with the custom DSL -->
            <plugin>
                <groupId>io.github.javaeden.orchid</groupId>
                <artifactId>orchid-maven-plugin</artifactId>
                <version>${orchid.version}</version>

                <!-- Add an Orchid Bundle. OrchidAll comes with all official themes included.
                     You must include a theme separately when using the OrchidBlog bundle.
                     Any additional plugins may be added as dependencies here as well. -->
                <dependencies>
                    <dependency>
                        <groupId>io.github.javaeden.orchid</groupId>
                        <artifactId>OrchidAll</artifactId>
                        <version>${orchid.version}</version>
                    </dependency>
                </dependencies>

                <configuration>
                    <!-- Theme is required -->
                    <theme>${theme}</theme>
                    
                    <!-- The following properties are optional -->
                    <version>${project.version}</version>
                    <baseUrl>${baseUrl}</baseUrl>                        <!-- a baseUrl prepended to all generated links. Defaults to '/' -->
                    <srcDir>path/to/new/source/directory</srcDir>        <!-- defaults to 'src/orchid/resources' -->
                    <destDir>path/to/new/destination/directory</destDir> <!-- defaults to 'target/docs/orchid' -->
                    <runTask>build</runTask>                             <!-- specify a task to run with 'mvn orchid:run' -->
                </configuration>
            </plugin>
        </plugins>
    </build>

    <!-- Orchid uses dependencies from both Jcenter and Jitpack, so both must be included. jcenter also includes 
         everything available from MavenCentral, while Jitpack makes accessible any Github project. -->
    <pluginRepositories>
        <pluginRepository>
            <id>jcenter</id>
            <name>bintray-plugins</name>
            <url>http://jcenter.bintray.com</url>
        </pluginRepository>
        <pluginRepository>
            <id>kotlinx</id>
            <url>https://kotlin.bintray.com/kotlinx</url>
        </pluginRepository>
        <pluginRepository>
            <id>orchid-bintray</id>
            <url>https://dl.bintray.com/javaeden/Orchid</url>
        </pluginRepository>
        <pluginRepository>
            <id>eden-bintray</id>
            <url>https://dl.bintray.com/javaeden/Eden</url>
        </pluginRepository>
        <pluginRepository>
            <id>jitpack</id>
            <url>https://jitpack.io</url>
        </pluginRepository>
    </pluginRepositories>
</project>

You can now run Orchid in the following ways:

  1. ./mvn orchid:run - Runs an Orchid task. The runTask property should be specified in pom.xml or passed as a Maven system property (-Dorchid.runTask=build). The task help will show a list of all tasks that can be run given the plugins currently installed.
  2. ./mvn orchid:build - Runs the Orchid build task a single time then exits. The resulting Orchid site will be in target/docs/orchid unless the output directory has been changed. You can then view the site by starting any HTTP file server in the root of the output directory, or deploy this folder directly to your webserver.
  3. ./mvn orchid:watch - Runs the Orchid build task a single time, then begins watching the source directory for changes. Anytime a file is changes, the build will run again, and the resulting Orchid site will be in build/docs/orchid unless the output directory has been changed.
  4. ./mvn orchid:serve - Sets up a development server and watches files for changes. The site can be viewed at localhost:8080 (or the closest available port).
  5. ./mvn orchid:deploy - Runs the Orchid build, then deploys it using Orchid's deployment pipeline You can create and run your own deployment scripts, create a release on Github from changelogs, or publish the site directly to Github Pages or Netlify.

Using Scriptlets

If you're using Orchid to build a standalone site (not integrated as the docs for another project in the same repo), a full Gradle or Maven setup may be a bit overkill. Instead, you may use a tool like kscript to bootstrap and run Orchid yourself with a more minimalistic project structure. The basic API below is specifically created for kscript, but can be easily adapted for other JVM scripting tools, or used like a library and started from another application.

@file:MavenRepository("kotlinx", "https://kotlin.bintray.com/kotlinx")
@file:MavenRepository("orchid-bintray", "https://dl.bintray.com/javaeden/Orchid/")
@file:MavenRepository("eden-bintray", "https://dl.bintray.com/javaeden/Eden/")
@file:MavenRepository("jitpack", "https://jitpack.io")

@file:DependsOn("io.github.javaeden.orchid:OrchidAll:{version}")

import com.eden.orchid.Orchid
import com.eden.orchid.StandardModule

val flags = HashMap<String, Any?>()

// Theme is required
flags["theme"] = "{theme}"

// The following properties are optional
flags["version"] = "{project.version}"
flags["baseUrl"] = "{baseUrl}"                         // a baseUrl prepended to all generated links. Defaults to '/'
flags["srcDir"]  = "path/to/new/source/directory"      // defaults to './src'
flags["destDir"] = "path/to/new/destination/directory" // defaults to './site'
flags["runTask"] = "build"                             // specify a default task to run when not supplied on the command line

val modules = listOf(StandardModule.builder()
        .args(args) // pass in the array of command-line args and let Orchid parse them out
        .flags(flags) // pass a map with any additional args
        .build()
)
Orchid.getInstance().start(modules)

You can now start Orchid directly with its CLI, using the following commands:

  1. kscript ./path/to/scriptlet.kts <task> [--<flag> <flag value>] - Runs an Orchid task by name. Additional parameters may be specified after the task name like --theme Editorial, which take precedence over the default values specified in the scriptlet. The default tasks are:
    1. build - Runs the Orchid build task a single time then exits. The resulting Orchid site will be in build/docs/orchid unless the output directory has been changed. You can then view the site by starting any HTTP file server in the root of the output directory, or deploy this folder directly to your webserver.
    2. .watch - Runs the Orchid build task a single time, then begins watching the source directory for changes. Anytime a file is changes, the build will run again, and the resulting Orchid site will be in build/docs/orchid unless the output directory has been changed.
    3. serve - Sets up a development server and watches files for changes. The site can be viewed at localhost:8080 (or the closest available port).
    4. deploy - Runs the Orchid build, then deploys it using Orchid's deployment pipeline You can create and run your own deployment scripts, create a release on Github from changelogs, or publish the site directly to Github Pages or Netlify.
  2. kscript ./path/to/scriptlet.kts help - Print out basic usage and all available tasks and command-line options.

Example Orchid Sites

Development Progress

As of v0.7.35, Orchid is now stable and ready for general use, but is still under constant development. Features and APIs are mostly stable and are not expected to change significantly, but bugs will be fixed and new features added rapidly. All plugins, themes, bundles, and Gradle plugins should use the same version, the most recent is shown here.

Latest Version

The following lists all official Orchid packages:

License

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

Contributing

Please see CONTRIBUTING.md

Contact

Orchid is being actively developed by Casey Brooks. Please open an issue here with questions or bug/feature requests, or you can reach me directly at cjbrooks12@gmail.com.