Migration Guide
Migrating from version 1.3.x to 1.4.x
Only sbt >1.1.6 is supported.
ParadoxSitePlugin
ParadoxPlugin
is enabled whenever ParadoxSitePlugin
is enabled.
Paradox integration now uses the same configuration scopes as the sbt-paradox
plugin. Therefore when upgrading remove the Paradox
configuration scope from all of the sbt-paradox
settings. Note that sbt-site setting siteSubdirName
is still configured under the Paradox
configuration scope.
The default Paradox source directory has been changed to match the one defined in the sbt-paradox
, which is src/main/paradox
. To keep the previous default, add the following to the build: sourceDirectory in paradox := sourceDirectory.value
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]
.