Migrate to Docusaurus: Phase 1

[eed3si9n]

See also https://eed3si9n.com/sbt-website-update-2024/

Problem

sbt's website uses a combination of static site generators that were created by the Scala community, Pamflet for the guides and Paradox for the landing pages. Both of these have been stable, and over the years I was able to add features to Pamflet, like globalization support, which still make them decent options. However, given that I am not actively developing either of them, we should switch over to a static site generator of 2020s.

Solution

In https://eed3si9n.com/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, which I think is fairly popular among the Scala community as well. With integration with MDX, it's super flexible in terms of customization. Among the niceness of Docusaurus is that it's designed to handle both the landing pages and user guides. In this PR, I've only replaced the landing pages.

Landing page

As mentioned above, this PR replaces Paradox landing pages with Docusaurus.

2017 Lightbend blue/orange (current):
#491

after 2024 rewrite:

Besides the fact that the download lists are now programmatically generated, there are no material difference between the two.

sbt User Guide

sbt 1.x documentation is kept intact with Pamflet. sbt-site is capable of versioned documents, as long as each branch write to different directories. What I suggest we do next (phase 2) is that we cut a branch for 1.x, and keep the existing sbt 1.x document as-is, and patch the 1.x branch as necessary.

On develop branch, we can reboot the sbt 2.x documentation. As a sampler, I wrote Installing sbt runner page, which looks like this:

By working only on the sbt 2.x docs in this branch, we get the benefit of starting over but also keeping the git history for pages that we can reuse.

[ckipp01]

So no idea if you've had a good experience with algolia or not, but in the other repos I've maintained we had weird issues with it. One really great alternative that I found and that we use in Metals and the BSP repos is https://github.com/scalameta/metals/blob/167d069ddd7d6f7965e67fa9cfe39b12cd1977bb/website/docusaurus.config.js#L56 so you still get site search, but it's all generated locally. So there is no need for the external algolia integration. Just thought I'd drop this here if you're interested at all.

[eed3si9n]

We already use Algolia, and as far as I can tell, it works pretty well https://www.scala-sbt.org/. I'd be happy to iterate on this if local search is in fact better?

[ckipp01]

Nah, I don't know if it's better. Just if you ever hit on issues, know that there is an algolia alternative.

[adpi2]

By working only on the sbt 2.x docs in this branch, we get the benefit of starting over but also keeping the git history for pages that we can reuse.

I like the plan.

[adpi2]

One question though: did you consider using scaladoc instead? Does it provide all the feature that we need (for e.g., custom js component)?

[eed3si9n]

@adpi2 Yea, @ckipp01 brought it up on Slack. We could explore it for the actual documentation portion of the site, but I am not really sure if we should get ourselves into yet another static site generator, written in Scala, and mostly used by us. If so I could stick with Pamflet, which we have control over and handles globalization and runtime themes.