Helium landing page - avoid hard-coding of panel title

docs/src/03-preparing-content/03-theme-settings.md

@@ -849,10 +849,11 @@ Helium.defaults
         IconLink.external("https://twitter.com/abcdefg/", HeliumIcon.twitter)
       )
     ),
-    documentationLinks = Seq(
+    linkPanel = Some(LinkPanel(
+      "Documentation",
       TextLink.internal(Root / "doc-1.md", "Doc 1"),
       TextLink.internal(Root / "doc-2.md", "Doc 2")
-    ),
+    )),
     projectLinks = Seq(
       TextLink.internal(Root / "doc-1.md", "Text Link"),
       ButtonLink.external("http://somewhere.com/", "Button Label"),

io/src/main/resources/laika/helium/templates/landing.template.html

@@ -42,11 +42,11 @@
           <p>License</p>
           <p class="large">${_}</p>
         @:@
-        @:if(helium.site.landingPage.documentationLinks)
+        @:for(helium.site.landingPage.linkPanel)
           <div id="docs">
-            <p>Documentation</p>
+            <p>${helium.site.landingPage.linkPanel.title}</p>
             <ul>
-              @:for(helium.site.landingPage.documentationLinks)
+              @:for(helium.site.landingPage.linkPanel.links)
                 <li>${_}</li>
               @:@
             </ul>

io/src/main/scala/laika/helium/config/api.scala

@@ -726,6 +726,32 @@ private[helium] trait SiteOps extends SingleConfigOps with CopyOps {
     copyWith(helium.siteSettings.copy(content = newContent))
   }
 
+  @deprecated("use new method overload", "1.2.0")
+  def landingPage(
+      logo: Option[Image],
+      title: Option[String],
+      subtitle: Option[String],
+      latestReleases: Seq[ReleaseInfo],
+      license: Option[String],
+      titleLinks: Seq[ThemeLink],
+      documentationLinks: Seq[TextLink],
+      projectLinks: Seq[ThemeLinkSpan],
+      teasers: Seq[Teaser]
+  ): Helium = {
+    landingPage(
+      logo,
+      title,
+      subtitle,
+      latestReleases,
+      license,
+      titleLinks,
+      documentationLinks,
+      projectLinks,
+      teasers,
+      None
+    )
+  }
+
   /** Adds a dedicated landing page to the site that is tailored for software documentation sites.
     * By default no landing page will be included and the site will render the homepage (if present)
     * with the same default template as the main content pages.
@@ -741,15 +767,19 @@ private[helium] trait SiteOps extends SingleConfigOps with CopyOps {
     * style content right on the start page.
     * It can also be used to list adopters, provide a feature overview or links to presentations or videos.
     *
-    * @param logo                a logo to be placed on the left hand side of the header
-    * @param title               a title to be placed right under the logo
-    * @param subtitle            a subtitle to be place right under the title
-    * @param latestReleases      a set of release versions to display on the right side of the header
-    * @param license             the license info to render right under the release info
-    * @param titleLinks          a row of links to render beneath the subtitle on the left side of the header
-    * @param documentationLinks  a set of documentation links to render in a dedicated panel on the right side of the header
-    * @param projectLinks        a set of project links to render at the bottom of the right side of the header
-    * @param teasers             a set of teasers containing of headline and description to render below the header
+    * The parameter `documentationLinks` .
+    *
+    * @param logo               a logo to be placed on the left hand side of the header
+    * @param title              a title to be placed right under the logo
+    * @param subtitle           a subtitle to be place right under the title
+    * @param latestReleases     a set of release versions to display on the right side of the header
+    * @param license            the license info to render right under the release info
+    * @param titleLinks         a row of links to render beneath the subtitle on the left side of the header
+    * @param linkPanel          a set of documentation links to render in a dedicated panel on the right side of the header
+    * @param projectLinks       a set of project links to render at the bottom of the right side of the header
+    * @param teasers            a set of teasers containing of headline and description to render below the header
+    * @param documentationLinks deprecated and only kept for binary compatibility - use the new `linkPanel` parameter
+    *                           which also allows to specify a panel title
     */
   def landingPage(
       logo: Option[Image] = None,
@@ -760,19 +790,29 @@ private[helium] trait SiteOps extends SingleConfigOps with CopyOps {
       titleLinks: Seq[ThemeLink] = Nil,
       documentationLinks: Seq[TextLink] = Nil,
       projectLinks: Seq[ThemeLinkSpan] = Nil,
-      teasers: Seq[Teaser] = Nil
+      teasers: Seq[Teaser] = Nil,
+      linkPanel: Option[LinkPanel] = None
   ): Helium = {
-    val page       = LandingPage(
+
+    val panel = linkPanel match {
+      case Some(panel) => Some(panel)
+      case None        =>
+        if (documentationLinks.isEmpty) None
+        else Some(LinkPanel("Documentation", documentationLinks))
+    }
+
+    val page = LandingPage(
       logo,
       title,
       subtitle,
       latestReleases,
       license,
       titleLinks,
-      documentationLinks,
+      panel,
       projectLinks,
       teasers
     )
+
     val newContent = currentContent.copy(landingPage = Some(page))
     copyWith(helium.siteSettings.copy(content = newContent))
   }

io/src/main/scala/laika/helium/config/model.scala

@@ -87,6 +87,20 @@ object Favicon {
 
 }
 
+/** Represents link panel to be displayed on the top right side of the landing page.
+  *
+  * @param title the title shown at the top of the panel
+  * @param links the links to render inside the panel
+  */
+case class LinkPanel(title: String, links: Seq[TextLink])
+
+object LinkPanel {
+
+  def apply(title: String, link: TextLink, links: TextLink*): LinkPanel =
+    apply(title, link +: links)
+
+}
+
 /** Represents release info to be displayed on the landing page.
   *
   * This is specific for sites that serve as documentation for software projects.

io/src/main/scala/laika/helium/internal/config/layout.scala

@@ -109,7 +109,7 @@ private[helium] case class LandingPage(
     latestReleases: Seq[ReleaseInfo] = Nil,
     license: Option[String] = None,
     titleLinks: Seq[ThemeLink] = Nil,
-    documentationLinks: Seq[TextLink] = Nil,
+    linkPanel: Option[LinkPanel] = None,
     projectLinks: Seq[ThemeLinkSpan] = Nil,
     teasers: Seq[Teaser] = Nil
 ) {

io/src/main/scala/laika/helium/internal/generate/ConfigGenerator.scala

@@ -43,6 +43,13 @@ private[laika] object ConfigGenerator {
       .build
   }
 
+  implicit val linkPanelEncoder: ConfigEncoder[LinkPanel] = ConfigEncoder[LinkPanel] { panel =>
+    ConfigEncoder.ObjectBuilder.empty
+      .withValue("title", panel.title)
+      .withValue("links", panel.links)
+      .build
+  }
+
   private def buildTeaserRows(teasers: Seq[Teaser]): Seq[ObjectValue] = if (teasers.isEmpty) Nil
   else
     BalancedGroups.create(teasers.toVector, Math.ceil(teasers.size.toDouble / 3).toInt).map { row =>
@@ -78,7 +85,7 @@ private[laika] object ConfigGenerator {
         .withValue("latestReleases", landingPage.latestReleases)
         .withValue("license", landingPage.license)
         .withValue("titleLinks", titleLinks)
-        .withValue("documentationLinks", landingPage.documentationLinks)
+        .withValue("linkPanel", landingPage.linkPanel)
         .withValue("projectLinks", landingPage.projectLinks)
         .withValue("teaserRows", buildTeaserRows(landingPage.teasers))
         .withValue("headerStyle", headerStyle)

io/src/test/scala/laika/helium/HeliumLandingPageSpec.scala

@@ -138,7 +138,7 @@ class HeliumLandingPageSpec extends CatsEffectSuite with InputBuilder with Resul
          |<p>License</p>
          |<p class="large">MIT</p>
          |<div id="docs">
-         |<p>Documentation</p>
+         |<p>Project Info</p>
          |<ul>
          |<li><a class="text-link" href="doc-1.html">Doc 1</a></li>
          |<li><a class="text-link" href="doc-2.html">Doc 2</a></li>
@@ -172,9 +172,12 @@ class HeliumLandingPageSpec extends CatsEffectSuite with InputBuilder with Resul
             IconLink.external("https://twitter.com/abcdefg/", HeliumIcon.twitter)
           )
         ),
-        documentationLinks = Seq(
-          TextLink.internal(Root / "doc-1.md", "Doc 1"),
-          TextLink.internal(Root / "doc-2.md", "Doc 2")
+        linkPanel = Some(
+          LinkPanel(
+            "Project Info",
+            TextLink.internal(Root / "doc-1.md", "Doc 1"),
+            TextLink.internal(Root / "doc-2.md", "Doc 2")
+          )
         ),
         projectLinks = Seq(
           TextLink.internal(Root / "doc-1.md", "Text Link"),