Project Submission: Laika

[jenshalm]

Project Name

Laika

Project Short Description

Site and e-book generator and customizable text markup transformer for sbt, Scala and Scala.js

Project Type

In accordance with the Typelevel Charter, I am proposing the project be a:

• [x] Organization Project
• [ ] Affiliate Project

Project Management

• This project's Code of Conduct can be found at https://github.com/planet42/Laika/blob/main/CODE_OF_CONDUCT.md
• This project's license (Apache 2.0) can be found at https://github.com/planet42/Laika/blob/main/license.txt
• Laika's default theme contains font resources licensed under the Open Font License, which is also OSI approved: https://github.com/planet42/Laika/blob/main/io/src/main/resources/laika/helium/fonts/FiraMono/LICENSE

Motivation

• The move had recently been suggested by @armanbilge and @valencik.
• Laika is the documentation toolkit used internally by sbt-typelevel-site which in turn is now used by many Typelevel projects to produce their documentation (e.g. http4s or cats).
• Laika itself is built around the Typelevel stack (cats-effect, fs2, http4s).
• At the moment the project does not even have a secondary admin who could cut an emergency release when I am unavailable, which is a potential inconvenience or even risk for adopters.
• All those cats and kittens really deserve a dog for company (for those who don't know her: https://en.wikipedia.org/wiki/Laika).

About the Project

Laika has been in development for more than 10 years, growing from a small library to a fully-featured documentation toolkit. The manual can be found here and a first draft for the road map of the upcoming 1.0 release here.

It differs from other documentation tools used in the Scala community in several ways:

• The toolkit makes documentation for Scala projects contributor-friendly by not requiring the installation of any external tools or languages - it's a JVM-only solution that simply runs as part of your sbt build.

• The sbt plugin itself is only a very thin layer (about 2% of the code base) on top of Laika's library APIs. This means it can be used with other build tools, embedded in Scala applications or, with a subset of its functionality, with Scala.js.

• Instead of wrapping existing Java parsers, it comes with its own spec-compliant parsers for Markdown, reStructuredText and HOCON, as well as its own syntax highlighters and templating. This means it can be customized with functional Scala and consistent patterns throughout all layers of functionality.

• With its generic document AST that is not semantically tied to any specific input or output format it can also support use cases beyond just project documentation.

• It has built-in support for versioned documentation, maintained on multiple branches.

At the moment the project is released in 5 artefacts, but the internal structure is very modular so that further micro-libs could be extracted in the future in case of strong demand.

[jducoeur]

Makes sense to me -- it's gradually becoming a de facto standard for the community, so it seems reasonable to treat it as such.

[rossabaker]

@typelevel/steering: please vote with reaction on the issue. 👍 for yes, 👎 for no, 👀 to abstain.

Voting is open three business days (through Wednesday, May 3) and until quorum (7) is reached.

[rossabaker]

I'm delighted to see this. This is both a well-crafted project on its own, and something that has significantly reduced complexity and increased reliability by integrating it into our builds.

[samspills]

Just a big +1 to that, Laika is great (also shout out to the excellent docs 😻)

[rossabaker]

Hooray! Quorum is reached[^1] (minimum 7, got 7) and vote is affirmative (minimum 3/4, was unanimous). Next steps are tracked in #108.

[^1]: I need an emoji callback ... we were stuck on six and I stopped polling as often. I apologize for my lax vote counting on this one.