Creating microsites for your Scala projects

Note

A great plugin for the sbt build tool for Scala is sbt-microsites. It allows you to create a beautiful documentation website for your library/application with not a lot of effort. Keeps your documentation pretty and consistent and informs other people how to use your package!

It uses jekyll under the hood to render markdown files into a static website. And it's packaged into a convenient packageMicrosite command that can integrate easily with github-pages to create a project website. (e.g. your-username.github.io/your-project). You can also use custom domains.

Note: Requires sbt > or equal to 1.3.0

Setup

To set it up, I like to put it into a separate sbt subproject.

  1. In project/plugins.sbt, add the plugin

    addSbtPlugin("com.47deg"  % "sbt-microsites" % sbtMicrositesVersion)

    You also need to have jekyll installed.

  2. Add the subproject to build.sbt. By default your documentation markdown files live in docs in the root of the project.

    lazy val microsite = project
  .in(file("microsite"))
  .settings(
    scalaVersion := yourScalaVersion,
    micrositeName := "your-library",
    micrositeBaseUrl := "your-library",
    micrositeDocumentationUrl := "docs",
    micrositeDescription := "A very descriptive description",
    micrositeAuthor := "Yours truly",
    micrositeGithubOwner := "your-github-username",
    micrositeGithubRepo := "your-github-repository",
    skip in publish := true)
  .enablePlugins(MicrositesPlugin)

    And add it to your main project with .aggregate()

    lazy val myProject = project
  .in(file("."))
  .settings(projectSettings)
  .aggregate(microsite, core)

  3. An example structure for the docs folder would be the following

    docs/
  index.md
  guide/
    index.md

  4. Then, in the sbt shell, run publishMicrosite. To build and view locally, run makeMicrosite.

Now you've got a snappy website for your project! I always like to look at pretty documentation. It definitely raises the chances of me actually reading it.

For more information, you can visit the sbt-microsites microsite!

logo