From 7126fff943b5c81284f1abe2b56249a8a22021b8 Mon Sep 17 00:00:00 2001
From: Jens Halm <3116929+jenshalm@users.noreply.github.com>
Date: Mon, 24 Jun 2024 20:03:05 +0100
Subject: [PATCH] helium landing page - avoid hard-coding of panel title
---
.../03-preparing-content/03-theme-settings.md | 5 +-
.../helium/templates/landing.template.html | 6 +-
.../main/scala/laika/helium/config/api.scala | 64 +++++++++++++++----
.../scala/laika/helium/config/model.scala | 14 ++++
.../laika/helium/internal/config/layout.scala | 2 +-
.../internal/generate/ConfigGenerator.scala | 9 ++-
.../laika/helium/HeliumLandingPageSpec.scala | 11 ++--
7 files changed, 88 insertions(+), 23 deletions(-)
diff --git a/docs/src/03-preparing-content/03-theme-settings.md b/docs/src/03-preparing-content/03-theme-settings.md
index 041037ec8..583bb2b89 100644
--- a/docs/src/03-preparing-content/03-theme-settings.md
+++ b/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"),
diff --git a/io/src/main/resources/laika/helium/templates/landing.template.html b/io/src/main/resources/laika/helium/templates/landing.template.html
index 590779a04..f18d264fb 100644
--- a/io/src/main/resources/laika/helium/templates/landing.template.html
+++ b/io/src/main/resources/laika/helium/templates/landing.template.html
@@ -42,11 +42,11 @@
-
Documentation
+
${helium.site.landingPage.linkPanel.title}
- @:for(helium.site.landingPage.documentationLinks)
+ @:for(helium.site.landingPage.linkPanel.links)
- ${_}
@:@
diff --git a/io/src/main/scala/laika/helium/config/api.scala b/io/src/main/scala/laika/helium/config/api.scala
index 75d1ee85f..c5e6ac8a8 100644
--- a/io/src/main/scala/laika/helium/config/api.scala
+++ b/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))
}
diff --git a/io/src/main/scala/laika/helium/config/model.scala b/io/src/main/scala/laika/helium/config/model.scala
index 2feeba131..0020a426e 100644
--- a/io/src/main/scala/laika/helium/config/model.scala
+++ b/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.
diff --git a/io/src/main/scala/laika/helium/internal/config/layout.scala b/io/src/main/scala/laika/helium/internal/config/layout.scala
index b5c53948e..4844bcf2d 100644
--- a/io/src/main/scala/laika/helium/internal/config/layout.scala
+++ b/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
) {
diff --git a/io/src/main/scala/laika/helium/internal/generate/ConfigGenerator.scala b/io/src/main/scala/laika/helium/internal/generate/ConfigGenerator.scala
index 079e208d7..2a769794e 100644
--- a/io/src/main/scala/laika/helium/internal/generate/ConfigGenerator.scala
+++ b/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)
diff --git a/io/src/test/scala/laika/helium/HeliumLandingPageSpec.scala b/io/src/test/scala/laika/helium/HeliumLandingPageSpec.scala
index 604605375..1d7be70c5 100644
--- a/io/src/test/scala/laika/helium/HeliumLandingPageSpec.scala
+++ b/io/src/test/scala/laika/helium/HeliumLandingPageSpec.scala
@@ -138,7 +138,7 @@ class HeliumLandingPageSpec extends CatsEffectSuite with InputBuilder with Resul
|
License
|
MIT
|
- |
Documentation
+ |
Project Info
|
|- Doc 1
|- Doc 2
@@ -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"),