About

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

Installation

dependencies {
    orchidRuntime("io.github.javaeden.orchid:OrchidGithub:0.21.2")
}

<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>OrchidGithub</artifactId>
    <version>0.21.2</version>
    <type>pom</type>
</dependency>

libraryDependencies += "io.github.javaeden.orchid" % "OrchidGithub" % "0.21.2"

@file:DependsOn("io.github.javaeden.orchid:OrchidGithub:0.21.2")

Demo

• Run GithubWikiAdapterTest for 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

Custom domains are supported for Github Pages sites by adding a CNAME file to the site as it is deployed. Since 0.19.0, Orchid will do this automatically based on your site's configured base URL if it does not end in .github.io. You will still need to configure DNS records with your domain registrar to point your domain to the Github Pages site, as described in this help article.

For versions earlier than 0.19.0, you will need to create the CNAME file automatically. As this file needs to be in the deployed site's root, and not your repo root, this will require the OrchidPages plugin to be able to create the necessary file. Create pages/CNAME file in your site resources (with no file extension) and add the following contents to it (replacing the domain with your own). Be sure that it's copied directly, with no extra newlines at the top or end, otherwise Github will not read the file properly.

---
renderMode: raw
usePrettyUrl: false
---
www.example.com

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.