Simplify configuring "related projects" nav area

[Daenyth]

Right now adding related projects is very verbose (and not well documented);

sbt-typelevel/build.sbt

Lines 223 to 242 in 2e82571

	tlSiteHelium ~= {
	import laika.helium.config._
	_.site.mainNavigation(appendLinks = Seq(
	ThemeNavigationSection(
	"Related Projects",
	TextLink.external("https://github.com/typelevel/typelevel.g8", "typelevel.g8"),
	TextLink.external("https://www.scala-sbt.org/", "sbt"),
	TextLink
	.external("https://github.com/portable-scala/sbt-crossproject", "sbt-crossproject"),
	TextLink.external("https://github.com/lightbend/mima", "MiMa"),
	TextLink.external("https://scalameta.org/mdoc/", "mdoc"),
	TextLink.external("https://typelevel.org/Laika/", "Laika"),
	TextLink.external("https://github.com/sbt/sbt-unidoc", "sbt-unidoc"),
	TextLink.external(
	"https://github.com/scalacenter/sbt-dependency-submission",
	"sbt-dependency-submission"),
	TextLink
	.external("https://github.com/scala-steward-org/scala-steward", "Scala Steward")
	)
	))

It would be nice if we had a setting key so we can do something like;

tlSiteRelatedProjects ++= Seq("http://example.com" -> "example")

Having the more powerful version available is nice, but doing the most common thing should be easy

[jenshalm]

I agree to both, that it should be better documented and that it is too verbose at the moment. But I'd advice against re-introducing tlSiteRelatedProjects and suggest improvements are made without it. I try to explain the motivation below as it is relevant to other areas of potential improvements, too.

The old, deprecated key is problematic for a number of reasons: 1) It hardcodes the assumption that there is only one extra section, 2) it hardcodes the assumption the section is titled "Related Projects" (outside of TL projects this is not a very realistic assumption), 3) it forces everyone with only slightly different requirements to use an entirely different configuration approach, 4) that other approach would still be too verbose, 5) we'd need to document and explain both approaches which is a confusing mess.

I'd suggest that instead we first improve documentation in this project to include at least one concrete example for how to modify the Helium config in sbt-tl before pointing to the Laika docs. And then think about avoiding the verbosity which is an improvement for Laika and would require a ticket there, not here.

One idea would be to add an overload that captures the fact that having only text links is the most common scenario:

laikaTheme := tlSiteHelium.value
  .site.mainNavigation(appendLinks = Seq(
    ThemeNavigationSection("Related Projects",
      "http://example-1.com" -> "Example 1",
      "http://example-2.com" -> "Example 2"
    )
  ))

which is not too far from:

tlSiteRelatedProjects ++= Seq(
    "http://example-1.com" -> "Example 1",
    "http://example-2.com" -> "Example 2"
)

This avoids the scenario of saving 2 lines for some use cases while complicating and essentially worsening the UX for everything else.

In my view that would be the best approach in general: Adding improvements for theme configuration to Laika and not this plugin. The distinction between the two is roughly this: Laika's own sbt plugin is very lightweight, with zero dependencies on other sbt plugins, and general purpose. You could manage your recipe collection with it, not just project documentation. sbt-typelevel-site OTOH is the opposite: it's the uber-plugin that pulls down half the internet and serves as a glue plugin for sbt-typelevel and Laika, primarily focussing on integrating Laika with mdoc and publishing to GitHub (plus some specific theme extensions for TL projects). New keys introduced by this plugin should imho ideally focus on these integration scenarios and not on duplicating configuration approaches in Laika in a different form.

[j-mie6]

👍 to Jens comment, Parsley was glad to see that key removed! It was annoying to require related projects when we don't really have any

[j-mie6]

That said, what about instead of offering configuration we/Laika offer combinators? So something like:

def relatedProjectsNavigation(prjs: (String, String)*) = ThemeNavigationSection( 
       "Related Projects", 
       prjs.map {
          case (prj, link) => TextLink.external(link, prj)
       }: _*)

can be provided by someone, then your configuration would be:

 tlSiteHelium ~= { 
   import laika.helium.config._ 
   _.site.mainNavigation(appendLinks = Seq(relatedProjectsNavigation(
       "typelevel.g8" -> "https://github.com/typelevel/typelevel.g8", "typelevel.g8"),
       "sbt" -> "https://www.scala-sbt.org/", 
       "sbt-crossproject" -> "https://github.com/portable-scala/sbt-crossproject", "sbt-crossproject", 
       "MiMa" -> "https://github.com/lightbend/mima",
       "mdoc" -> "https://scalameta.org/mdoc/", 
       ...) 
     ) 

[jenshalm]

Imho that only moves the problem: it's still hardcoding one very specific use case without doing anything about the others whereas what I proposed above reduces verbosity for all use cases. I don't see the need to hardcode a specific section headline in the API anywhere.

[j-mie6]

I somehow managed to completely miss your proposal being effectively identical to mine but more general 😂, yeah I'm in favour of that