Start a new Orchid project

The simplest way to get started with Orchid is to use the Orchid Starter repo as a base.

  1. git clone https://github.com/JavaEden/OrchidStarter.git
    • Clone the Starter repo anywhere you want on your system
  2. cd OrchidStarter
    • Navigate into the directory containing the Starter repo
  3. ./gradlew orchidServe
    • Run Orchid using the included Gradle wrapper. No complicated and brittle gemfiles, NPM packages, or anything else required. As long as you have a Java JDK installed, Orchid works right out-of-the-box without any configuration or system packages to install.
    • All available commands:
      • gradle orchidBuild - Build Orchid once then exit.
      • gradle orchidWatch - Watch Orchid for changes, rebuilding whenever a file changes.
      • gradle orchidServe - Start a local development server to view your output site. Also watches Orchid for changes, rebuilding whenever a file changes.
      • gradle orchidDeploy - Build Orchid once, deploy the built site through the publication pipeline, then exit.
      • gradle assemble - Not strictly an Orchid command, but if you are set up with the OrchidJavadoc plugin, this will run Orchid from the Javadoc tool instead of generating the standard Javadocs.

Deploy to Netlify

Alternatively, you can simply click the "Deploy to Netlify" button below to automatically clone, build, and deploy the Starter repo to the Netlify CDN.

Deploy to Netlify

Integrate Orchid into an existing project

The Starter repo is great if you are setting up Orchid as a standalone website, but Orchid was designed to be integrated into any project. Orchid can be set up from Gradle, Maven, or started manually through scriptlets or from another application.

Gradle

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

 1 plugins {
 2     // Add the official Orchid Gradle plugin so you can use Orchid with the custom DSL   
 3     id "com.eden.orchidPlugin" version "0.13.0"
 4 }
 5 
 6 repositories {
 7     // Orchid uses dependencies from both Jcenter and Jitpack, so both must be included. jcenter also includes 
 8     // everything available from MavenCentral, while Jitpack makes accessible any Github project.
 9     jcenter()
10     maven { url "https://kotlin.bintray.com/kotlinx" }
11     maven { url 'https://dl.bintray.com/javaeden/Orchid/' }
12     maven { url 'https://dl.bintray.com/javaeden/Eden/' }
13     maven { url 'https://jitpack.io' }
14 }
15 
16 dependencies {
17     // Add an Orchid Bundle. OrchidAll comes with all official themes included.
18     // You must include a theme separately when using the OrchidBlog bundle.
19     // Any additional plugins may be added as dependencies here as well.
20     orchidRuntime 'io.github.javaeden.orchid:OrchidAll:0.13.0'
21 }
22 
23 orchid {
24     // Theme is required
25     theme   = "{theme}"
26     
27     // The following properties are optional
28     version = "${project.version}"
29     baseUrl = "{baseUrl}"                         // a baseUrl prepended to all generated links. Defaults to '/'
30     srcDir  = "path/to/new/source/directory"      // defaults to 'src/orchid/resources'
31     destDir = "path/to/new/destination/directory" // defaults to 'build/docs/orchid'
32     runTask = "build"                             // specify a task to run with 'gradle orchidRun'
33 }

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.

Maven

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

 1 <project>
 2     ...
 3     
 4     <properties>
 5         <orchid.version>0.13.0</orchid.version>
 6     </properties>
 7 
 8     <build>
 9         <plugins>
10             <!-- Add the official Orchid Gradle plugin so you can use Orchid with the custom DSL -->
11             <plugin>
12                 <groupId>io.github.javaeden.orchid</groupId>
13                 <artifactId>orchid-maven-plugin</artifactId>
14                 <version>${orchid.version}</version>
15 
16                 <!-- Add an Orchid Bundle. OrchidAll comes with all official themes included.
17                      You must include a theme separately when using the OrchidBlog bundle.
18                      Any additional plugins may be added as dependencies here as well. -->
19                 <dependencies>
20                     <dependency>
21                         <groupId>io.github.javaeden.orchid</groupId>
22                         <artifactId>OrchidAll</artifactId>
23                         <version>${orchid.version}</version>
24                     </dependency>
25                 </dependencies>
26 
27                 <configuration>
28                     <!-- Theme is required -->
29                     <theme>${theme}</theme>
30                     
31                     <!-- The following properties are optional -->
32                     <version>${project.version}</version>
33                     <baseUrl>${baseUrl}</baseUrl>                        <!-- a baseUrl prepended to all generated links. Defaults to '/' -->
34                     <srcDir>path/to/new/source/directory</srcDir>        <!-- defaults to 'src/orchid/resources' -->
35                     <destDir>path/to/new/destination/directory</destDir> <!-- defaults to 'target/docs/orchid' -->
36                     <runTask>build</runTask>                             <!-- specify a task to run with 'mvn orchid:run' -->
37                 </configuration>
38             </plugin>
39         </plugins>
40     </build>
41 
42     <!-- Orchid uses dependencies from both Jcenter and Jitpack, so both must be included. jcenter also includes 
43          everything available from MavenCentral, while Jitpack makes accessible any Github project. -->
44     <pluginRepositories>
45         <pluginRepository>
46             <id>jcenter</id>
47             <name>bintray-plugins</name>
48             <url>http://jcenter.bintray.com</url>
49         </pluginRepository>
50         <pluginRepository>
51             <id>kotlinx</id>
52             <url>https://kotlin.bintray.com/kotlinx</url>
53         </pluginRepository>
54         <pluginRepository>
55             <id>orchid-bintray</id>
56             <url>https://dl.bintray.com/javaeden/Orchid</url>
57         </pluginRepository>
58         <pluginRepository>
59             <id>eden-bintray</id>
60             <url>https://dl.bintray.com/javaeden/Eden</url>
61         </pluginRepository>
62         <pluginRepository>
63             <id>jitpack</id>
64             <url>https://jitpack.io</url>
65         </pluginRepository>
66     </pluginRepositories>
67 </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.

kscript

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.

 1 @file:MavenRepository("kotlinx", "https://kotlin.bintray.com/kotlinx")
 2 @file:MavenRepository("orchid-bintray", "https://dl.bintray.com/javaeden/Orchid/")
 3 @file:MavenRepository("eden-bintray", "https://dl.bintray.com/javaeden/Eden/")
 4 @file:MavenRepository("jitpack", "https://jitpack.io")
 5 
 6 @file:DependsOn("io.github.javaeden.orchid:OrchidAll:0.13.0")
 7 
 8 import com.eden.orchid.Orchid
 9 import com.eden.orchid.StandardModule
10 
11 val flags = HashMap<String, Any?>()
12 
13 // Theme is required
14 flags["theme"] = "{theme}"
15 
16 // The following properties are optional
17 flags["version"] = "0.13.0"
18 flags["baseUrl"] = "{baseUrl}"                         // a baseUrl prepended to all generated links. Defaults to '/'
19 flags["srcDir"]  = "path/to/new/source/directory"      // defaults to './src'
20 flags["destDir"] = "path/to/new/destination/directory" // defaults to './site'
21 flags["runTask"] = "build"                             // specify a default task to run when not supplied on the command line
22 
23 val modules = listOf(StandardModule.builder()
24         .args(args) // pass in the array of command-line args and let Orchid parse them out
25         .flags(flags) // pass a map with any additional args
26         .build()
27 )
28 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.

See Also:

Edit this page