GitHub Pages

Commit your site to git and publish it to Github Pages.

See Also: Edit this page

Description

The ghPages Publisher allows you to upload your site to GithubPages.

To use the githubReleases publisher, you'll need to provide Orchid with a githubToken containing a Personal Access Token from Github. Since PATs are confidential and allow anyone who has it complete access to your account, you should set this as an environment variable and add it to your Gradle orchid config from that variable rather than committing it to source control.

orchid {
    ...
    githubToken = "${System.getenv('GITHUB_TOKEN')}" 
    // or 'githubToken' in an environment variable without this line
}

After your PAT is set up, you'll need to set up your repo on GitHub with a gh-pages branch. Orchid will initialize a new local git repo and push it to this branch, overwriting anything currently in that branch.

The username property is the user which issued the PAT, and it is also the organization hosting the repository on GitHub. You can authenticate with a different user than is hosting the repository by setting the repo as username/repo.

Example Usage

services:
  publications: 
    stages: 
      - type: ghPages
        username: 'cjbrooks12'
        repo: 'JavaEden/Orchid'
      #    or
      - type: ghPages
        username: 'cjbrooks12'
        repo: 'cjbrooks12.github.io' # becomes cjbrooks12/cjbrooks12.github.io 

API Documentation

Commit your site directly to Github Pages. It can even keep old versions of your site for versioning documentation.

Default Config
# config.yml
...
services:
  publications:
    stages:
      githubPages:
        githubUrl: github.com
        repo: empty string
        username: empty string
Key Type Default Value Description
githubUrl String github.com

The URL for a self-hosted Github Enterprise installation.

repo String empty string

The repository to push to, as [username/repo], or just [repo] to use the authenticating username.

username String empty string

The user or organization with push access to your repo, used for authenticating with GitHub.

Key Type Default Value Description
allData Map<String, Object> {}

All options passed to this object.

branch String empty string

The branch to push to.

commitEmail String orchid@orchid

The email on the commit.

commitMessage String Deploy to GitHub Pages from Orchid.

The commit message to attach to this deploy.

commitUsername String Orchid

The username on the commit.

dry boolean false
latestDirName String latest

The name of the 'latest' directory used for the VersionedBranchWithLatest publish type.

order int 0

Manually set the order in which this publisher executes

publishType PublishType CleanBranch

The type of publication to use for Github Pages.

  • CleanBranch: Create a new branch with no history and force-push to the remote. Overwrites existing branch completely.
  • CleanBranchMaintainHistory: Clone existing branch, remove all files, then push to the remote. Overwrites all files, but maintains history.
  • VersionedBranch: Clone existing branch, add current site to a versioned subfolder, then push to the remote. Maintains history and all prior versions' content.
  • VersionedBranchWithLatest: Clone existing branch, add current site to a 'latest' and a versioned subfolder, then force-push to the remote. Maintains history and all prior versions' content.
Key Type Description
allPublishers Site Config

Configure this item with additional options merged in from config.yml, from the object at the archetype key. Dots in the key indicate sub-objects within the site config.