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 following to your project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.3.1")

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 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:

mappings in makeSite ++= 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:

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

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

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:

publishSite

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.