Getting Started

This page will help you get started with sbt-site and teach you the basic concepts.

Setup

To enable the plugin in your sbt project, add the sbt-site module for the site generator you use to your project/plugins.sbt file:

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.

Adding Content to Your Site

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 src/site:

siteSourceDirectory := target.value / "generated-stuff"

Additional files outside of siteSourceDirectory can be added via sbt file mappings:

copysourcemakeSite / 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 addMappingsToSiteDir:

copysource// 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)

Previewing the Site

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:

previewFixedPort := Some(9999)

To disable browser auto-open, use the key previewLaunchBrowser:

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"

Packaging and Publishing

To create a zip package of the site run package-site.

To also include this zip file as an artifact when running publish, add the following to your build.sbt:

copysourcepublishSite

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.

copysourceaddSbtPlugin(
  ("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")
)