Skip to main content

Config

Essential settings#

Add set DocusaurPlugin in the build.sbt.

e.g.)

lazy val root = (project in file("."))
.enablePlugins(DocusaurPlugin)

and add the following setting keys to the project.

docusaurDir := file("path" / "to" / "docusaurus-website"),
docusaurBuildDir := docusaurDir.value / "build" / "path",

To publish the website to GitHub Page, add the following keys as well. However, these can be automatically set by sbt-github-pages if missing.

// Optional. It's automatically done by sbt-github-pages
gitHubPagesOrgName := "USERNAME_OR_ORG",
// Optional. It's automatically done by sbt-github-pages
gitHubPagesRepoName := "YOUR_PROJECT",
note

sbt-docusaur uses sbt-github-pages to publish the website to GitHub Pages.

e.g.)

lazy val root = (project in file("."))
.enablePlugins(DocusaurPlugin)
.settings(
organization := "com.some.org",
name := "project-name",
docusaurDir := (ThisBuild / baseDirectory).value / "website",
docusaurBuildDir := docusaurDir.value / "build",
gitHubPagesOrgName := "github-username",
gitHubPagesRepoName := "project-name"
)

Docusaur Directory *#

important

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

NameValue TypeDefault
docusaurDirFile

The path to the Docusaurus webiste.

e.g.) If the Docusaurus website is located at project-root/website/

docusaurDir := (ThisBuild / baseDirectory).value / "website"

Docusaur Build Directory *#

important

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

NameValue TypeDefault
docusaurBuildDirFile

The path to the build path of Docusaurus webiste.

e.g.) If the Docusaurus website is located at project-root/website/ and the build path is at project-root/website/build

docusaurBuildDir := docusaurDir.value / "build"

If the Docusaurus website is located at project-root/website/ and the build path is at project-root/website/build/some-project

docusaurBuildDir := docusaurDir.value / "build" / "some-project"

GitHub Org Name / Username#

important

This key must be set by the user of this plugin to publish the website to GitHub Pages.

However, it is automatically done by sbt-github-pages so you don't need to set it up unless you want to set it otherwise.

NameValue TypeDefault
gitHubPagesOrgNameStringValue obtained from calling git remote

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

e.g.) If the repo is https://github.com/Kevin-Lee/sbt-docusaur

gitHubPagesOrgName := "Kevin-Lee"
note

You don't need to set it up as sbt-github-pages does it automatically with the value from git remote.

GitHub Repo Name#

important

This key must be set by the user of this plugin to publish the website to GitHub Pages.

However, it is automatically done by sbt-github-pages so you don't need to set it up unless you want to set it otherwise.

NameValue TypeDefault
gitHubPagesRepoNameStringValue obtained from calling git remote

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

e.g.) If the repo is https://github.com/Kevin-Lee/sbt-docusaur

gitHubPagesRepoName := "sbt-docusaur"
note

You don't need to set it up as sbt-github-pages does it automatically with the value from git remote.

More Settings#

npm Path#

NameValue TypeDefault
docusaurNpmPathOption[File]None

This is a setting key to specify the path to npm. By default, it uses npm found in the PATH env var. So you don't need to specify it unless you want to use npm from some other path.

Algolia Config Filename (Optional)#

NameValue TypeDefault
docusaurAlgoliaConfigFilenameStringsys.env.getOrElse("ALGOLIA_CONFIG_FILENAME", "algolia.config.json")

The name of Algolia config file.

Algolia ApiKey (Optional)#

NameValue TypeDefault
docusaurAlgoliaApiKeyOption[String]sys.env.get("ALGOLIA_API_KEY")

Algolia API Key. If missing, Algolia config with an empty object ({}) is created.

Algolia Index Name (Optional)#

NameValue TypeDefault
docusaurAlgoliaIndexNameOption[String]sys.env.get("ALGOLIA_INDEX_NAME")

Algolia index name. If missing, Algolia config with an empty object ({}) is created.

Google Analytics Config File (Optional)#

NameValue TypeDefault
docusaurGoogleAnalyticsConfigFilenameStringsys.env.getOrElse("GA_CONFIG_FILENAME", "google-analytics.config.json")

e.g.)

export GA_CONFIG_FILENAME=ga-conf.json

Or

docusaurGoogleAnalyticsConfigFilename := "ga-conf.json"

Google Analytics Tracking ID (Optional)#

NameValue TypeDefault
docusaurGoogleAnalyticsTrackingIdOption[String]sys.env.getOrElse("GA_TRACKING_ID")

Google Analytics Tracking ID. If missing, Google Analytics config with an empty object ({}) is created.

e.g.)

export GA_TRACKING_ID=UA-000000-1

Or

docusaurGoogleAnalyticsTrackingId := Some("UA-000000-1")

Google Analytics Anonymize IP (Optional)#

NameValue TypeDefault
docusaurGoogleAnalyticsAnonymizeIpOption[Boolean]sys.env.getOrElse("GA_ANONYMIZE_IP")

If missing, no anonymizeIP is written in the config file.

e.g.)

export GA_ANONYMIZE_IP=true

Or

docusaurGoogleAnalyticsAnonymizeIp := Some(true)

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

Or

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"

Or

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"

Or

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"}'

Or

gitHubPagesGitHubHeaders := Map("User-Agent" -> "app-doc-publisher")