sbt-typelevel-site

sbt-typelevel-site is an optional plugin for generating websites with mdoc and Laika and deploying to GitHub Pages from CI. You can add it to your build alongside either the sbt-typelevel or sbt-typelevel-ci-release plugin or also use it stand-alone.

Quick start

project/plugins.sbt

addSbtPlugin("org.typelevel" % "sbt-typelevel-site" % "0.4.18")

build.sbt

// publish website from this branch
ThisBuild / tlSitePublishBranch := Some("main")

lazy val docs = project.in(file("site")).enablePlugins(TypelevelSitePlugin)

Place your .md files in the docs/ directory of your project. To preview locally, run docs/tlSitePreview. This will start a preview server at http://localhost:4242.

The site is generated using mdoc and Laika and published to the gh-pages branch on every push to the specified branch.

You will also need to configure your repository settings:

  1. Grant "Read and write" permissions to workflows. This enables them to push to the gh-pages branch. https://github.com/{user}/{repo}/settings/actions
  2. Set the GitHub pages source to the / (root) directory on the gh-pages branch. https://github.com/{user}/{repo}/settings/pages

How can I include my project version on the website?

sbt-typelevel-site automatically adds VERSION and SNAPSHOT_VERSION to the mdocVariables setting which can be used with variable injection.

For example, the sbt-typelevel VERSION is 0.4.18 and SNAPSHOT_VERSION is 0.4.18-10-beeaf03-SNAPSHOT.

How can I publish "unidoc" API docs?

If you generate your API documentation with sbt-unidoc, you can use the TypelevelUnidocPlugin to publish a Scaladoc-only artifact to Sonatype/Maven alongside your library artifacts. This makes it possible to browse your unidocs at javadoc.io; for example, the sbt-typelevel API docs are published like this.

// Make sure to add to your root aggregate so it gets published!
lazy val unidocs = project
  .in(file("unidocs"))
  .enablePlugins(TypelevelUnidocPlugin) // also enables the ScalaUnidocPlugin
  .settings(
    name := "woozle-docs",
    ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(core.jvm, heffalump)
  )

How can I customize my website's appearance?

We refer you to the comprehensive Laika manual and specifically the laikaTheme setting.