This page will help you get started with sbt-site and teach you the basic concepts.
To enable the plugin in your sbt project, add the sbt-site module for the site generator you use to your
addSbtPlugin("com.github.sbt" % "sbt-site-paradox" % "1.5.0")
The group ID changed to
com.github.sbt with sbt-site version 1.5.0 and the plugin was split into modules per site generator.
When you run
makeSite, your project’s webpage is generated in the
target/site directory. By default, all files under
src/site that match the includeFilter setting (by default *.html, *.css, *.png, *.jpg, *.gif, *.swf) are included in
target/site. If your site mainly contains static content but you want to replace for example a version string in some of the pages you can use preprocessing to substitute variables.
In addition to static content, you can also generated content as part of the build process and add it to your site. sbt-site has support for adding Scaladoc and provides several site generators such as Jekyll and Sphinx which can be used for managing your site’s content.
If you already have a way to generate a site and all you want is to use sbt-site to package and maybe include API documentation, you can configure
siteSourceDirectory to point to the directory containing the generated site files instead of
siteSourceDirectory := target.value / "generated-stuff"
Additional files outside of
siteSourceDirectory can be added via sbt file mappings:
makeSite / mappings ++= Seq( file("LICENSE") -> "LICENSE", file("src/assets/favicon.ico") -> "favicon.ico" )
If you want to add files from an sbt task to a site sub-directory use the provided
// Define a custom setting and set it to the directory path val someDirName = settingKey[String]("Some dir name") someDirName := "someFancySource" addMappingsToSiteDir(Compile / packageSrc / mappings, someDirName) // Or using siteSubdirName scoped to a sbt task or a configuration ScalaUnidoc / siteSubdirName := "api" addMappingsToSiteDir(ScalaUnidoc/ packageDoc / mappings, ScalaUnidoc / siteSubdirName)
addMappingsToSiteDir requires that the site sub-directory name is passed via a setting’s key. In most cases this can be achieved by scoping sbt-site’s
siteSubdirName setting’s key to the task providing the mappings as shown above.
To preview your generated site, you can run
previewSite which launches a static web server, or
previewAuto which launches a dynamic server updating its content at each modification in your source files. Both launch the server on port 4000 and attempts to connect your browser to http://localhost:4000/. To change the server port, use the key
previewFixedPort := Some(9999)
To disable browser auto-open, use the key
previewLaunchBrowser := false
In case the page to start preview from isn’t the site root, set
previewPath to the desired path:
previewPath := "docs/index.html"
To create a zip package of the site run
To also include this zip file as an artifact when running
publish, add the following to your
Once you have generated and packaged your site the next step is to publish it. The publishing section discusses several mechanisms, such as sbt-ghpages. You may need to exclude the Scala XML dependency.
addSbtPlugin( ("com.github.sbt" % "sbt-ghpages" % "0.7.0") // sbt-ghpages depends on sbt-site 1.4.1, which pulls Scala XML 1.x .exclude("org.scala-lang.modules", "scala-xml_2.12") )