Open root

Static Site Generators

When designing a new website, you may want to research the available options. Jamstack provides a list of static site generators which can be grouped by language. Further research on GitHub can also unveil alternatives. The options considered for this website are listed below, grouped by language.

Scala

The following repos can be quickly ruled out because they are not actively maintained:

That leaves the following options:

Ultimately, Laika was chosen to generate this website. Hepek seemed like a good option, especially with its Play integration, but its documentation paled in comparison to the other two options. Since Paradox is maintained by Lightbend/Typesafe, it immediately had some appeal. However, the Laika documentation lists support for features like AST rewriting, navigation tree generation, and Zio integration lent it the edge.

Laika

For the purposes of this website, Laika is used to transform a directory of Markdown files to HTML. Its feature set extends beyond this use case, of course. It also supports input in reStructuredText format & output in EPUB or PDF format. According to its creator, Laika is commonly used for Scala library projects' documentation websites and books. To get acquainted with Laika, use the demo app.

When you begin using Laika, take note of the documentation's warning regarding fenced code blocks so that you aren't surprised if you run into issues:

Fenced code blocks need a preceding bland line to be recognized by Laika's parser for now.
Documentation

Laika is exquisitely-documented. Not only are the features described, but also low-level details about how to use & extend the APIs are provided. Many subtle details of this website are powered by Laika functionality. Below is a list of links to interesting sections of the Laika documentation.

One exciting feature this website does not currently leverage but which seems very powerful is:

[Laika can be used] In server-side Scala applications, e.g. for transforming user input in markup syntax or as part of document processing pipelines

Swift

While some of these options are compelling within the Swift ecosystem, none of them even come close to matching the power that Laika provides.