search term:

sbt website update 2024

This is a writeup on sbt’s website updates, some concrete, others more of half-baked ideas.


I’ve been the primary maintainer of the site since 2014. Though I have written some of the pages, most of the content had been written by Mark and Havoc by the time I took over. You can see on 2014 archive that the site was Sphinx doc.

The first things I did in 2014 on the site was to migrate from Sphix, which used reStructuredText, to Markdown on Pamflet, a static site generator created by Nathan, and later I inherited.

I’ve also created a landing page using Nanoc. The landing page was rebanded in 2015 to Typesafe color scheme, and in 2017 Lightbend blue/orange color scheme, which still remains today. At some point, I switched from Nanoc to Paradox too.

2017 Lightbend blue/orange (current): 2017 version

Last year, Lightbend transferred the ownership of sbt as well as the site to Scala Center.


I’ve been relatively happy with Paradox and Pamflet, but I also think it’s time to switch to another static site generator that are actively maintained. In sbt 2.0 ideas I wrote:

Maybe this is also a good timing to switch to some other static site generator like MkDocs or Docusaurus.

I’ve opted for Docusaurus, created by Meta, and fairly popular among Scala open source projects. It comes preconfigured to support landing pages, docs, and blog. Even though it’s a static site generator, during the generation it can run components written in JavaScript, and it’s extensible.

2023-02-18 Update: When I realized that I can’t seem to get PDF output easily from Docusaurus, I switched to mdBook for the documentation part.

Phase 1: Landing pages

I’ve sent a pull request sbt/website#1173 to migrate the landing pages from Paradox to Docusaurus.

2024 rewite: 2024 version

The picture of the ryōanji dry garden is the same image from the original 2014 landing page. Besides the fact that the download lists are now programmatically generated, there are no material difference between the two.

MDX allows you to embed JavaScript into Markdown:

import HomepageVersions from '@site/src/components/HomepageVersions';

### Previous releases


<HomepageVersions />

The component is implemented as JavaScript that iterates over a list of versions to produce a table. As of the pull request, Paradox is gone, but sbt 1.x docs is still using Pamflet.

Phase 2: User documentation

One benefit of static site generator is that it’s fairly easy to create versioned documentation. All you need to do is output the HTML files in separate directories during deployment.

2023-02-18 Update: When I realized that I can’t seem to get PDF output easily from Docusaurus, I switched to mdBook for the documentation part.

I sent sbt/website#1188, which lets us branch out 1.x documentation for 1.x branch, and start a new sbt 2.x documentation on develop branch using mdBook.

This approach has many benefits:

  1. 2.x is a clean slate, so we don’t have to worry about breaking existing links for sbt 1.x docs.
  2. We can work on and publish 2.x docs incrementally.
  3. As we reorganize the docs, we can also document any sbt 2.x features or features that were added in 1.x.
  4. For any pages that we can reuse, we can keep the git history, as opposed to having both 1.x and 2.x both in one branch.

Setup page (2024-02) using mdBook: Setup page 2024-02 version

Doc reorganization

I would be remiss if I didn’t mention Daniele Procida’s 2017 ‘What nobody tells you about documentation’ talk aka ‘The four kinds of documentation’ / The Documentation System. Per Procida, there are four kinds of documentation:

  1. learning-oriented quick start guide
  2. goal-oriented how-to guides
  3. understanding-oriented explanation
  4. information-oriented reference material

He calls the first one tutorial, but I think quick start guide is probably more apt since the term spans over the first three kinds. In particular, there was an emphasis on not explaining things in quick start or how-to guides as well who the target audiences are.

I am not fully sure where documents on testing or publishing may fit into the above categorization, but in general it would be good to calibrate what we need to include into Getting Started guide, and what we can move out.

We could also get some insight from other software documentations, both build tools and non-build tools:

Some thoughts:

Let me know if you have recommendation for some software documentation, especially the ones that teaches users concepts, not just detailed description.


Since I’ve listed a bunch of static site generators, I should also note that this post was authored using Hugo.