Investigate migrating site to Laika?

[valencik]

Our current site was built with the help of 47 Degrees (now Xebia) and has served us well for the last couple of years.
However there remains some issues that I believe would be best solved by migrating to Laika.

Unfamiliar Tech Stack

The current site uses jekyll which, while popular overall, is not particularly familiar to the Scala ecosystem.
The majority of Typelevel projects now use sbt-typelevel and Laika to manage their builds and construct a documentation site.

Typelevel developers are used to the build tooling required to update a project's documentation, it's just sbt!
The current site requires a ruby installation, and while there is a nix flake to aid with that, I have still seen several people avoid building the website locally because of unfamiliarity with the setup.

Page Discoverability

The current site's main navigation feature is the top level nav bar.

And then within one of those top level pages we can further split into sub sections on that same page:

I believe this navigation structure is too limiting.
There hasn't always been an obvious place for new content to live.

Consider the Platforms page https://typelevel.org/platforms/ which largely repeats the content found in the Projects page.
This perhaps instead could have been a sub-section of "Projects". Or each platform could have been a sub-section of Projects.

Additionally there's the GSoC page https://typelevel.org/gsoc/. This currently isn't discoverable through the main navigation.

I think the left navigation panel, that Laika offers is a much easier way to display and discover the pages available to the user.

What Next?

I am not asking for someone to go off and rebuild our site in sbt-typelevel and Laika just yet.
I think we need to discuss and think through the pro/cons.
What features does the current site have that might be hard to offer in a Laika site?
What other benefits would we get from migrating to a Laika site?

[valencik]

Some possible challenges

Project page

The Projects page, https://typelevel.org/projects/, has the job of quickly listing over a hundred different projects.
We have to figure out the best way to translate this into Laika, we have some options.

This could be a giant markdown file, which would then make it very easy to add structure, as has been proposed before: #272
Or it could be something wild like an HTML page that Laika includes verbatim and is actually built via some scala + scalatags

RSS

The current site's blog section has an RSS feed: https://typelevel.org/blog/feed.rss
This isn't an out of the box feature of Laika.

[jducoeur]

I have a weird negative knee-jerk that Laika doesn't look like a community page, it looks like a documentation page. I think that's irrational pattern-matching in my head, so I don't think it's a serious argument -- just noting that reaction.

I certainly like the idea in practical terms -- I'm one of the people who has tried to get things working locally and failed a couple of times, washing up on the rocky shoals of Ruby. And I love it in principle: we should be using our own tools when appropriate. But I need to better familiarize myself with how Laika works.

Editing here to add more thoughts as I read into this (possibly naive, since I don't yet entirely understand the topic):

• Maybe we should use HOCON for structure instead of Markdown for the Projects page? That feels more correct to me, if Laika provides the ability to interate a template over an input array. (Basically "mailmerge" it.) On further reading -- plausible, but it would be a bit abusive, since HOCON is mainly intended as an optional approach for configuration, rather than data. But Laika is flexible enough that it looks like this could be done fairly easily.
• Otherwise, I would probably opine that one small file per Project is the best way to go, in a well-defined directory, same as blog articles, and we just combine the Projects as desired for each relevant page.
• At least in airy theory, RSS should just be another Renderer, right? So step one might be to add that feature to Laika, with our news feed as a motivating use case, and see how that works. That, in turn, would probably help us understand how well Laika fits with our requirements. (Since that's another "mailmerge" sort of use case.)
• Hypothesis: I'm not actually 100% certain RSS even needs a custom Renderer. It feels like it could possibly be done using the HTML renderer and highly-customized templates that just don't actually spit out HTML. Worth experimenting.
• We might want to come up with a custom theme that matches our "branding", and is structured more like we expect. I think that could fix my "this looks like library documentation" twitch. I like this in principle, but looking at how much code is involved with the default Helium theme, it might be a bunch of work. And Helium is flexible enough that we may be able to get something reasonably good just by customizing the theme templates to better match our needs.
• Yeah, Laika's template mechanism has a first-class @for(...) mechanism built in. (Unsurprisingly, the level of power is comparable to what I'm used to in Play.) So building up a page from data looks entirely feasible.
• Question: can we easily define our own variables on a per-page basis? (Eg, "platforms", "affiliate/organization", etc.) Answer: looks like yes, this is what the @fragment() directive is for, as well as header-defined substitution variables. But that's content -- can we do semantic variables that we filter on? Answer: yes, but doing interesting things may require creating our own Directives to process them.

[jducoeur]

Having now skimmed the full Laika docs:

I'm confident that we could do this -- Laika's level of flexibility is stellar, and it's just a library at its heart, so I'd be quite surprised if there were any insuperable problems.

The more interesting question is how much custom Scala code we would need in order to get the results we want. My instinct is that that wouldn't be too bad (I think we're looking more at custom templates than anything else), but it needs a bunch of experimentation.

So my gut says, "yes, probably". IMO, the right next step would be essentially a research spike -- a slash-and-burn experimental project focused entirely on the interesting structural problems. The objective would be something that uses a modest amount of completely fake data, and doesn't necessarily look at all good (programmer art, basically), but shows off all the critical structural bits.

In particular, this hypothetical research project would:

• Show a way to define "projects", and slice-and-dice them along different dimensions for different pages.
• Provide a summary page for the "blog".
• Provide an XML output page for the "blog". (For purposes of this experiment, doesn't need to be proper RSS, just showing that we can generate arbitrary XML in a file named "feed.rss".)

I don't really have time myself (I've already let myself be nerdsniped for the entire morning on this), but I'm halfway tempted to bootstrap this experiment and start kicking the tires...

[jducoeur]

There's an somewhat separate conversation to be had about information architecture. If we go down this road (especially if we leave Laika's sidebar in place), IMO we need to be conscious about how that sidebar gets structured, so that it includes all the bits we care about and provides good discoverability, without getting excessively long.

That said, I think that's a second-order discussion, to hold off on until we're confident that we know what we're doing technically.

[rossabaker]

If we don't have the ambition for all the customization that would be required of Laika, Hugo is basically Jekyll with a much longer halflife of its radioactive bits. I use it everywhere I'm not trying to squeeze everything into a JVM.