Migration Guide
Migrating from version 0.x.x to 1.x.x
The 1.x.x release of sbt-site marks the conversion to the AutoPlugin facility, first introduced in sbt 0.13.5.
Because sbt best practices have evolved with the introduction of AutoPlugin, this upgrade to sbt-site has resulted in a number of “breaking changes” insofar as the way site generation is configured (the same functionality remains).
Enabling Generators
The biggest of the breaking changes is the use of enablePlugins(<plugin object>) instead of calls of the form site.xyzSupport().
The base plugin (SitePlugin) is enabled by default, so files in the src/site directory are processed according to the default settings. Invocation of other generators must be adjusted accordingly.
| Generator | Previous (0.x) | New (1.x) |
|---|---|---|
| Base | site.settings |
automatic |
| Preprocess | site.preprocessSite() |
enablePlugins(PreprocessPlugin) |
| Jekyll | site.jekyllSupport() |
enablePlugins(JekyllPlugin) |
| Sphinx | site.sphinxSupport() |
enablePlugins(SphinxPlugin) |
| Pamflet | site.pamfletSupport() |
enablePlugins(PamfletPlugin) |
| Nanoc | site.nanocSupport() |
enablePlugins(NanocPlugin) |
| Asciidoctor | site.asciidoctorSupport() |
enablePlugins(AsciidoctorPlugin) |
| Scaladoc | site.includeScaladoc() |
enablePlugins(SiteScaladocPlugin) |
Configuring Site Subdirectory
Each of the generators can be instructed to populate a subdirectory under the target/site destination. This is done by setting the siteSubdirName key in the configuration scope of the generator. For example, the following build.sbt fragment enables the Jekyll and Scaladoc generators, and configures their output to be target/site/jekyll-goodness and target/site/jekyll-goodness/api, respectively.
enablePlugins(JekyllPlugin, SiteScaladocPlugin)
siteSubdirName in Jekyll := "jekyll-goodness"
siteSubdirName in SiteScaladoc := "jekyll-goodness/api"
Adding Custom Mappings to a Site Directory
Content added using:
site.addMappingsToSiteDir(mappings: TaskKey[Seq[(File,String)]], nestedDirectory: String)
has been replaced with:
addMappingsToSiteDir(mappings: TaskKey[Seq[(File, String)]], nestedDirectory: SettingKey[String])
The following examples show how you can define nested directory via a custom setting or by scoping siteSubdirName to either an sbt key or configuration:
// Define a custom setting and set it to the directory path
val someDirName = settingKey[String]("Some dir name")
someDirName := "someFancySource"
addMappingsToSiteDir(mappings in (Compile, packageSrc), someDirName)
// Or using siteSubdirName scoped to a sbt task or a configuration
siteSubdirName in ScalaUnidoc := "api"
addMappingsToSiteDir(mappings in (ScalaUnidoc, packageDoc), siteSubdirName in ScalaUnidoc)Miscellaneous
In the PreprocessPlugin, the key preprocessExts: SettingKey[Set[String]] has been replaced by preprocessIncludeFilter: SettingKey[FileFilter].