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.
- Features
- Dependencies
- Anatomy of the API
- Transforming Strings: This is a good starting point to demonstrate a proof-of-concept.
- Using cats.IO, Monix or Zio
- Entire Directories as Input: This website is generated by feeding in a directory of Markdown files as described within the documentation.
- Separate Parsing and Rendering
- Configuration
- Directory Structure
- Title Documents: The directory names in this website's sidebar are generated via this feature.
- Auto-generated Navigation
- Linking to API Documentation
- Generating Navigation Trees: This feature is used to generate the sidebar of this website.
- Breadcrumbs
- Auto-numbering
- Creating Templates: A template exists alongside all the Markdown files to power this feature.
- The Document AST
- AST Rewriting: This feature is used to customize elements within the AST before they are transformed into HTML.
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.