sbt-jbake

Build JBake sites with sbt.

Table of Contents

• Overview
• Usage
• Configuration settings
• Hints
• Sample setup
• We love contributions
• Changelog
  • sbt-jbake 0.1.2 - 2019-05-23
  • sbt-jbake 0.1.1 - 2019-05-23
  • sbt-jbake 0.1.0 - 2019-05-06

Overview

Users of the plugin maintain their documentation in AsciiDoc (other markup languages ar also supported) files in a particular source directory. These sources will be baked by JBake into HTML files via the jbakeBuild task.

Normally, the HTML files require additional files such as style sheets or java script libraries. For a complete site these files must be copied to the jbake outputput directory structure, so that the HTML files can reference them properly.

Assembling the site from the baked AsciiDoc files and the additional files is performed via the jbakeSite task.

Usage

Add to /project/plugins.sbt of your project

// Generate site with JBake
addSbtPlugin("de.wayofquality.sbt" % "sbt-jbake" % "0.1.2")

Configuration settings

The following settings and tasks are available.

jbakeVersion : SettingKey[String]

The JBake version to be used.

jbakeLib : SettingKey[ModuleID]

The JBake binary distribution to be used. This defaults to download the official binary distribution from Bintray, but you can override this, if you want to use another one.

default

jbakeLib := "jbake" % "jbake" % jbakeVersion.value from s"https://dl.bintray.com/jbake/binary/jbake-${jbakeVersion.value}-bin.zip"

The jbakeLib settings will also be added as a library dependency to the project using the plugin.

jbakeInputDir : SettingKey[File]

The input directory for the site generation.

default

jbakeInputDir := baseDirectory.value

jbakeOutputDir : SettingKey[File]

The directory for the generated site.

default

jbakeOutputDir := target.value / "site",

jbakeMode : SettingKey[String]

Run JBake in build or serve mode. This setting only applies to jbakeBuild.

default

jbakeMode := "build",

jbakeAsciidocAttributes : TaskKey[Map[String, String]]

Asciidoctor attributes to passed to Asciidoctor. The default settings support the use of some AsciiDoc diagram generators. We have tested it with graphviz, plantUML and mermaid.

Note	For mermaid, the node binary directory must be set correctly AND mermaid must have been installed via npm.

default

jbakeAsciidocAttributes := Map(
  "imagesdir" -> "images",
  "imagesoutdir" -> "images"
) ++ jbakeNodeBinDir.value.map(nd =>
  "mermaid" -> nd.getAbsolutePath()
)

jbakeNodeBinDir : TaskKey[Option[File]]

The directory where we can find the executables for node modules. (Needed, when using e.g. mermaid)

default

jbakeNodeBinDir := None

jbakeSiteAssets : TaskKey[Map[File,File]]

Assets to be included in the site. The map keys are the source file to be copied, the values are the corresponding destination files. These files will only be copied in jbakeSite.

default

jbakeSiteAssets := Map.empty

Hints

• To generate the site with sbt into a directory that can be published, you will use jbakeSite and perhaps run the publish job after the sbt build.

• If you are working on the documentation, you can initially run a jbakeSite to make sure all the required assets are copied into the correct place within the generated site directory.

  Afterwards, you can run ;set Compile/jbakeMode := "serve"; jbakeBuild. This will start JBake itself in server mode, so that you can preview the site locally.

Sample setup

We are using this plugin to build the documentation of the Blended project. You can have a look at our source directory, which contains a complete setup for JBake including templates and other stuff we need to build the site.

For this project we are using the ScalaJS bundler to transform scss files into css that can then be used in the HTML files.

The associated sbt project definition and webpack config complete the configuration.

We love contributions

Let us know when you are using the plugin. Feel free to create an issue in case you run into problems. Even better, clone the repo, fix the issue and create a pull request.

Changelog

sbt-jbake 0.1.2 - 2019-05-23

• Added jbakeVersion setting.

• Remove scope Compile from default settings.

sbt-jbake 0.1.1 - 2019-05-23

• Automatically add the jbake binary distribution as a library dependency, so that it will be cached in the local Ivy repository. The module ID can be set via the jbakeLib plugin setting.

sbt-jbake 0.1.0 - 2019-05-06

• Initial public release