Skip to main content

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.

gitHubPagesSiteDir := baseDirectory.value / "path/to/github-pages-root"

// These aren't mandatory unless sbt-github-pages can't infer them from `git remote`
gitHubPagesOrgName := "USERNAME_OR_ORG",
gitHubPagesRepoName := "YOUR_PROJECT",

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
gitHubPagesOrgNameStringValue obtained from calling git remote

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

Most of the times you won't need to set this setting, since sbt-github-pages will try to read it from the git remote information.

e.g.)

gitHubPagesOrgName := "Kevin-Lee"

GitHub Repo Name *​

important

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

NameValue TypeDefault
gitHubPagesRepoNameStringValue obtained from calling git remote

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

Most of the times you won't need to set this setting, since sbt-github-pages will try to read it from the git remote information.

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")