Orchid

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

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

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

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.

Quick Start
1. Gradle
2. Maven
3. KScript
Example Orchid Sites
Development Progress
License
Contributing
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.

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

./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.
./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.
./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.
./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).
./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>jitpack</id>
            <url>https://jitpack.io</url>
        </pluginRepository>
    </pluginRepositories>
</project>

You can now run Orchid in the following ways:

./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.
./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.
./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.
./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).
./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("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:

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

The following lists all official Orchid packages:

opencollective / orchid Goto Github PK

orchid's Introduction

orchid's People

Contributors

Stargazers

Watchers

Recommend Projects

Recommend Topics

Recommend Org