Quick-Start
Get set up with a new or existing project.
Start a new Orchid project
The simplest way to get started with Orchid is to use the Orchid Starter repo as a base.
git clone https://github.com/orchidhq/OrchidStarter.git
cd OrchidStarter
./gradlew orchidServe
Deploy to Netlify
Alternatively, you can simply click the "Deploy to Netlify" button below to automatically clone, build, and deploy the OrchidStarter repo to the Netlify CDN.
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:
// build.gradle
plugins {
// Add the official Orchid Gradle plugin so you can use Orchid with the custom DSL
id "com.eden.orchidPlugin" version "0.18.0"
}
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:0.18.0'
}
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. TherunTaskshould be specified inbuild.gradleor passed as a Gradle project property (-PorchidRunTask=build). The taskhelpwill 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 inbuild/docs/orchidunless 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 inbuild/docs/orchidunless the output directory has been changed../gradlew orchidServe- Sets up a development server and watches files for changes. The site can be viewed atlocalhost: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.
Maven
To use Orchid from a Maven project, setup your project's pom.xml file like so:
<!-- pom.xml -->
<project>
...
<properties>
<orchid.version>0.18.0</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. TherunTaskproperty should be specified inpom.xmlor passed as a Maven system property (-Dorchid.runTask=build). The taskhelpwill 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 intarget/docs/orchidunless 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 inbuild/docs/orchidunless the output directory has been changed../mvn orchid:serve- Sets up a development server and watches files for changes. The site can be viewed atlocalhost: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.
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.
// orchid.kts
@file:MavenRepository("kotlinx", "https://kotlin.bintray.com/kotlinx")
@file:MavenRepository("jitpack", "https://jitpack.io")
@file:DependsOn("io.github.javaeden.orchid:OrchidAll:0.18.0")
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"] = "0.18.0"
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:build- Runs the Orchid build task a single time then exits. The resulting Orchid site will be inbuild/docs/orchidunless 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..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 inbuild/docs/orchidunless the output directory has been changed.serve- Sets up a development server and watches files for changes. The site can be viewed atlocalhost:8080(or the closest available port).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.
sbt
Your sbt project should look something like this:
amazeballs/
|
|—— build.sbt
|
|—— src/
| |
| +—— main/
| |
| +—— scala/
| | |
| | +—— Amazeballs.scala
| |
| +—— orchid/
| |
| +—— resources/ <== ORCHID SOURCE FILES GO HERE
| |
|—— project/ +- homepage.md
|
+—— build.properties
|
+—— plugins.sbt
If you wish to integrate orchid into an sbt project, you'll use the Orchid sbt plugin. To install it
in your project, you'll need to ensure that at least the following is included in your project/plugins.sbt:
resolvers += Resolver.jcenterRepo // hosts Orchid and its components
resolvers += Resolver.bintrayRepo("javaeden", "sbt-plugins") // hosts Orchid SBT plugin
addSbtPlugin( "io.github.javaeden.orchid" % "sbt-orchid" % "0.18.0" )
(You will usually want to include a bit more than this in project/plugins.sbt. The much richer project/plugins.sbt example below is a better starting point.)
Then place the source files for your Orchid site in src/main/orchid/resources.
Now, on the sbt command line you can run:
orchidBuild- Runs the Orchid build task a single time then completes. The resulting Orchid site will be intarget/orchidunless theorchidDestinationsetting has been customized. 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.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 intarget/orchidunless theorchidDestinationsetting has been customized.orchidServe- Sets up a development server and watches files for changes. The site can be viewed atlocalhost:8080(or the closest available port).orchidDeploy- Runs the Orchid build, then deploys the generated site using Orchid's deployment pipeline You can create and run your own deployment scripts, create and release on Github from changelogs, or publish the site directly to Github Pages or Netlify.
You can also run these tasks directly from your OS command line as sbt orchidBuild, sbt orchidWatch, sbt orchidServe, or sbt orchidDeploy.
You can run Orchid-related tasks generically with orchidRun. For example, the following are all equivalent to running orchidBuild:
> orchidRun buildfrom the sbt command line$ sbt "orchidRun build"from your OS command line$ sbt -Dorchid.runTask=build orchidRunfrom your OS command line
Available commands are build, deploy, and serve.
sbt plugin configuration
basic
In your project's build.sbt file, you will usually want to configure an Orchid theme. That's just:
orchidTheme := "BsDoc"
However, for this to work, you will need to make sure the theme and any other features your site relies upon are available to the build. Orchid offers a very rich feature set, made available via distinct, dynamically loaded dependencies. In order to use these features, you'll want to add them as dependies of the build, not your project.
The easiest way to do this is just include these dependencies in your project/plugins.sbt file.
Below is a very rich example project/plugins.sbt file. You can use any of the main Orchid features
simply by uncommenting the associated dependencies. For the BsDoc theme to be made available, for example,
you'd want to uncomment the line containing libraryDependencies += orchidComponent( "OrchidBsDoc" ).
rich project/plugins.sbt example
// build.sbt
resolvers += Resolver.jcenterRepo // hosts Orchid and its components
resolvers += Resolver.bintrayRepo("javaeden", "sbt-plugins") // hosts Orchid SBT plugin
val OrchidVersion = "0.18.0"
addSbtPlugin("io.github.javaeden.orchid" % "sbt-orchid" % OrchidVersion)
/*
* Add desired Orchid components to the build
*/
def orchidComponent( name : String ) = "io.github.javaeden.orchid" % name % OrchidVersion
/*
* The plugin includes OrchidCore already as a dependency,
* but explicitly specifying it helps ensure version consistency
* with other components.
*/
libraryDependencies += orchidComponent( "OrchidCore" )
/*
* Uncomment the components you desire
*/
/* Themes -- see https://orchid.run/themes */
/* Don't forget to set 'orchidTheme' in build.sbt! */
// libraryDependencies += orchidComponent( "OrchidBsDoc" )
// libraryDependencies += orchidComponent( "OrchidCopper" )
// libraryDependencies += orchidComponent( "OrchidEditorial" )
// libraryDependencies += orchidComponent( "OrchidFutureImperfect" )
/* Plugins -- see https://orchid.run/plugins */
// libraryDependencies += orchidComponent( "OrchidPages" )
// libraryDependencies += orchidComponent( "OrchidPosts" )
// libraryDependencies += orchidComponent( "OrchidPluginDocs" )
// libraryDependencies += orchidComponent( "OrchidAsciidoc" )
// libraryDependencies += orchidComponent( "OrchidAzure" )
// libraryDependencies += orchidComponent( "OrchidBible" )
// libraryDependencies += orchidComponent( "OrchidBitbucket" )
// libraryDependencies += orchidComponent( "OrchidChangelog" )
// libraryDependencies += orchidComponent( "OrchidDiagrams" )
// libraryDependencies += orchidComponent( "OrchidForms" )
// libraryDependencies += orchidComponent( "OrchidGithub" )
// libraryDependencies += orchidComponent( "OrchidGitlab" )
// libraryDependencies += orchidComponent( "OrchidGroovydoc" )
// libraryDependencies += orchidComponent( "OrchidJavadoc" )
// libraryDependencies += orchidComponent( "OrchidKSS" )
// libraryDependencies += orchidComponent( "OrchidKotlindoc" )
// libraryDependencies += orchidComponent( "OrchidNetlify" )
// libraryDependencies += orchidComponent( "OrchidNetlifyCMS" )
// libraryDependencies += orchidComponent( "OrchidPresentations" )
// libraryDependencies += orchidComponent( "OrchidSearch" )
// libraryDependencies += orchidComponent( "OrchidSwagger" )
// libraryDependencies += orchidComponent( "OrchidSwiftdoc" )
// libraryDependencies += orchidComponent( "OrchidSyntaxHighlighter" )
// libraryDependencies += orchidComponent( "OrchidTaxonomies" )
// libraryDependencies += orchidComponent( "OrchidWiki" )
// libraryDependencies += orchidComponent( "OrchidWritersBlocks" )
all build.sbt settings
orchidBaseUrl~ The base URL for generted site linksorchidDestination~ The directory into which orchid sites are generated (target/orchidby default)orchidDryDeploy~ Allows running a dry deploy instead of a full deploy (falseby default)orchidEnvironment~ The environment used to run the orchid site. (debugby default)orchidPort~ The port to run the dev server on. (8080by default)orchidResources~ The directory of source documents Orchid directly transforms (src/main/orchid/resources, or more preciselyorchidSource.value/ "resources", by default)orchidSource~ The top-level directory for orchid-related source documents (src/main/orchidby default)orchidTheme~ The theme that will be imposed on the generated orchid site (ThemeDefaultby default)orchidVersion~ The version of the orchid site that will be generated (Your sbt project'sversionby default)