Config

Add set GitHubPagesPlugin in the build.sbt.

Essential settings

You probably need only these three setting keys in your project config to publish GitHub Pages.

gitHubPagesOrgName := "USERNAME_OR_ORG",
gitHubPagesRepoName := "YOUR_PROJECT",
gitHubPagesSiteDir := baseDirectory.value / "path/to/github-pages-root"

e.g.)

lazy val root = (project in file("."))
.enablePlugins(GitHubPagesPlugin)
.settings(
name := "YOUR_PROJECT",
gitHubPagesOrgName := "USERNAME_OR_ORG",
gitHubPagesRepoName := "YOUR_PROJECT",
gitHubPagesSiteDir := baseDirectory.value / "path/to/github-pages-root"
)

GitHub Org Name / Username *

important

This key must be set by the user of this plugin.

NameValue TypeDefault
gitHubPagesOrgNameString

The GitHub organization name (or username) (i.e.OrgName from https://github.com/OrgName/RepoName)

e.g.)

gitHubPagesOrgName := "Kevin-Lee"

GitHub Repo Name *

important

This key must be set by the user of this plugin.

NameValue TypeDefault
gitHubPagesRepoNameString

The GitHub project repository name (i.e. RepoName from https://github.com/OrgName/RepoName)

e.g.)

gitHubPagesRepoName := "sbt-github-pages"

Site Dir *

important

This key must be set by the user of this plugin.

NameValue TypeDefault
gitHubPagesSiteDirFile

The folder contains all the files to be pushed to the GitHub Pages branch specified at gitHubPagesBranch.

e.g.)

Project structure

Project
Root ─┬─ dirA
β”œβ”€ dirB
└─ website─┬─ dirC
β”œβ”€ dirD
β”œβ”€ build <== Contains website files
└─ node_modules
gitHubPagesSiteDir := (ThisBuild / baseDirectory).value / "website" / "build"

More Settings

GitHub Pages Branch

NameValue TypeDefault
gitHubPagesBranchStringgh-pages

A setting key to set the GitHub Pages branch. By default, it's gh-pages but if your project repos uses a different branch you can set it up using this key.

e.g.) If you want to use main branch instead of gh-pages,

gitHubPagesBranch := "main"

NoJekyll

NameValue TypeDefault
gitHubPagesNoJekyllBooleantrue

The flag to decide whether to add .nojekyll.

GitHub Pages, by default, uses Jekyll to generate a static website. However, sbt-github-pages is designed to publish a ready to go website to GitHub Pages. So it's necessary to tell GitHub Pages not to use Jeklly and ask to use whatever is sent to the GitHub Pages branch as is. It can be done by placing a .nojekyll file.

If you want GitHub Pages to use Jekyll and generate a static website, set gitHubPagesNoJekyll to false.

e.g.) Let GitHub Pages use Jekyll to generate a website.

gitHubPagesNoJekyll := false

GitHubToken

NameValue TypeDefault
gitHubPagesGitHubTokenOption[String]sys.env.get("GITHUB_TOKEN")
Warning!!!

DO NOT hard-code the actual GitHub auth token String here. Use an environment variable instead.

The GitHub authentication token (default: The value from environment variable GITHUB_TOKEN) If you're using GitHub Actions to publish, you don't need to set it up at all. GitHub provides the GitHub token in GitHub Actions build so you can just use it.

e.g.) In your GitHub Actions config yml file,

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
# ...
- name: Publish website
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
echo "> Publish GitHub Pages"
sbt publishToGitHubPages

e.g.) If you want to change it,

gitHubPagesGitHubToken := sys.env.get("SOME_OTHER_VAR")
Warning!!!

DO NOT hard-code the actual GitHub auth token String here. Use an environment variable instead.

Dirs To Ignore

NameValue TypeDefault
gitHubPagesDirsToIgnoreSet[String]Set("target", "bin", "output")

A list of directory names to be ignored when committing to the GitHub Pages branch.

e.g.) You add more or remove some.

gitHubPagesDirsToIgnore := Set("node_modules", "build", "output")

Ignore Dot Dirs

NameValue TypeDefault
gitHubPagesIgnoreDotDirsBooleantrue

A flag to indicate whether to ignore or not dot directories when committing to the GitHub Pages branch.

e.g.) To include all the dot dirs like .cache, .github, .idea, etc., set it to false.

gitHubPagesIgnoreDotDirs := false

Accepted Text Extensions

NameValue TypeDefault
gitHubPagesAcceptedTextExtensionsSet[String]Set(".md", ".css", ".html", ".xml", ".js", ".txt")

Accepted text files to create UTF-8 encoded String based blob. If the file's extension is not one of these, Base64 encoded blob is created.

Default:

Set(".md", ".css", ".html", ".xml", ".js", ".txt")

e.g.) You add more or remove some.

gitHubPagesAcceptedTextExtensions :=
Set(".json", ".js", ".css", ".html")

Accepted Text MaxLength

NameValue TypeDefault
gitHubPagesAcceptedTextMaxLengthInt10240

The max length of the bytes (Array[Byte]) of the file to commit. If the file byte size is greater than this, Base64 encoded blob is created.

e.g.) You can make it smaller.

gitHubPagesAcceptedTextMaxLength := 6144

Publish Commit Message

NameValue TypeDefault
gitHubPagesPublishCommitMessageStringENV VAR GITHUB_PAGES_PUBLISH_COMMIT_MESSAGE or Updated ${gitHubPagesBranch.value}

The commit message when publish to GitHub Pages.

First, it tries to get the value from the environment variable GITHUB_PAGES_PUBLISH_COMMIT_MESSAGE. If not found, the default value is s"Updated ${gitHubPagesBranch.value}"

Default:

gitHubPagesPublishCommitMessage :=
sys.env.getOrElse(
"GITHUB_PAGES_PUBLISH_COMMIT_MESSAGE",
s"Updated ${gitHubPagesBranch.value}"
)

e.g.) If you want to have a different message, you can change it.

gitHubPagesPublishCommitMessage := s"New stuff in my awesome website!!!"

Use GitHub Enterprise

sbt-github-pages support GitHub Enterprise

There are four properties can be used to use GitHub Enterprise. To set these up, get the right values from your company.

  • gitHubPagesGitHubBaseUrl
  • gitHubPagesGitHubAuthorizeUrl
  • gitHubPagesGitHubAccessTokenUrl
  • gitHubPagesGitHubHeaders

GitHub Enterprise - Base URL

NameValue TypeDefault
gitHubPagesGitHubBaseUrlStringENV VAR GITHUB_ENT_BASE_URL or https://api.github.com/

NOTE: The trailing slash is significant. So https://some.url.blah does not work. It should be https://some.url.blah/.

e.g.)

export GITHUB_ENT_BASE_URL="https://github.my-company.internal/api/v3/"
gitHubPagesGitHubBaseUrl := "https://github.my-company.internal/api/v3/"

GitHub Enterprise - Authorize URL

NameValue TypeDefault
gitHubPagesGitHubAuthorizeUrlStringENV VAR GITHUB_ENT_AUTHORIZE_URL or https://github.com/login/oauth/authorize?client_id=%s&redirect_uri=%s&scope=%s&state=%s

e.g.)

export GITHUB_ENT_AUTHORIZE_URL="https://github.my-company.internal/login/oauth/authorize?client_id=%s&redirect_uri=%s&scope=%s&state=%s"
gitHubPagesGitHubAuthorizeUrl :=
"https://github.my-company.internal/login/oauth/authorize?client_id=%s&redirect_uri=%s&scope=%s&state=%s"

GitHub Enterprise - Access Token URL

NameValue TypeDefault
gitHubPagesGitHubAccessTokenUrlStringENV VAR GITHUB_ENT_ACCESS_TOKEN_URL or https://github.com/login/oauth/access_token

e.g.)

export GITHUB_ENT_ACCESS_TOKEN_URL="https://github.my-company.internal/login/oauth/access_token"
gitHubPagesGitHubAccessTokenUrl :=
"https://github.my-company.internal/login/oauth/access_token"

GitHub Enterprise - Headers

NameValue TypeDefault
gitHubPagesGitHubHeadersMap[String, String]ENV VAR GITHUB_ENT_HEADERS or Map("User-Agent" -> "github4s")

e.g.) When using the environment variable, the value should be JSON containing String key to String value pairs. e.g.)

export GITHUB_ENT_HEADERS='{"User-Agent":"app-doc-publisher", "something-else":"blah"}'
gitHubPagesGitHubHeaders := Map("User-Agent" -> "app-doc-publisher")