Build and deploy beautiful, organic, modular documentation sites

Build and deploy beautiful, organic, modular documentation sites

OrchidGithub

Connect your Orchid site to GitHub services.

official wiki publication

About

OrchidGithub connects Orchid to Github's services, including integrating wikis, creating releases, and publishing your site directly to Github Pages.

Demo

Usage

Wiki Adapter

OrchidGithub comes with a github Wiki Adapter, to integrate a project wiki as an Orchid wiki section. This will clone the wiki repository and convert its contents to an Orchid wiki automatically. If a _Sidebar file exists in the wiki, pages will be ordered according to the order of links in that sidebar file. Otherwise, pages will be ordered alphabetically, with a summary page generated listing all pages in order.

# config.yml
wiki: 
  sections:
    userManual:
      adapter: 
        type: "github"
        repo: "[username/repo]" # the wiki attached to this project will be used

Github Pages Publisher

The githubPages publisher will take your rendered site and publish it to a static website on Github Pages. You must have a personal access token set for publication to work, see Configuration below.

# config.yml
services:
  publications:
    stages:
      - type: 'githubPages'
        username: '[username]' # the username which created the personal access token
        repo: '[username/repo]' # the repo to publish to

Github Releases Publisher

The githubReleases publisher will create a release on Github release notes from the OrchidChangelog plugin's latest changelog version.

# config.yml
services:
  publications:
    stages:
      - type: 'githubReleases'
        repo: '[username/repo]' # the repo to create a release on

Configuration

You must generate a personal access token from Github to successfully authenticate and allow Orchid to perform actions on your behalf, like publishing a site to Github Pages. This can be set as the githubToken environment variable, or passed to Orchid from Gradle.

// build.gradle
orchid {
    githubToken = project.property("githubToken")
}

Note that this token grants full access to your account, and should be treated like any normal password. Never check it in to your repository.

dependencies {
    orchidRuntime 'io.github.javaeden.orchid:orchidgithub:0.17.1'
}
<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>orchidgithub</artifactId>
    <version>0.17.1</version>
    <type>pom</type>
</dependency>
@file:DependsOn("io.github.javaeden.orchid:orchidgithub:0.17.1")