OrchidGithub
Connect your Orchid site to GitHub services.
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.