This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
The following commit(s) were added to refs/heads/master by this push:
new 78211ab Follow the declared breadcrumbs with the menu trail
78211ab is described below
commit 78211ab0d52612dfb84353a19e27a4dab9c98cb5
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 3 01:57:46 2026 +0000
Follow the declared breadcrumbs with the menu trail
Breadcrumbs derived from the menu applied only to documents without
declared breadcrumbs, but nearly every
site inherits some (Apache / Maven on all Maven sites), so the menu trail
never showed. The menus and menu
items that contain the document now follow the declared breadcrumbs,
without repeating a declared link. The
option is unreleased, so its @since moves from 2.1.1 to 2.2.0.
Closes #658
Closes #245
---
.../doxia/siterenderer/DefaultSiteRenderer.java | 23 +++++++--
.../doxia/siterenderer/SiteRenderingContext.java | 12 ++---
.../DeriveBreadcrumbsFromMenuTest.java | 54 ++++++++++++++++++----
3 files changed, 72 insertions(+), 17 deletions(-)
diff --git
a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
index efc7203..1b40e70 100644
---
a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
+++
b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
@@ -38,6 +38,7 @@ import java.io.Writer;
import java.net.URL;
import java.net.URLClassLoader;
import java.nio.file.Files;
+import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
@@ -367,6 +368,15 @@ public class DefaultSiteRenderer implements Renderer {
return false;
}
+ private static boolean containsHref(List<LinkItem> links, String href) {
+ for (LinkItem link : links) {
+ if (href.equals(link.getHref())) {
+ return true;
+ }
+ }
+ return false;
+ }
+
/** {@inheritDoc} */
public void render(
Collection<DocumentRenderer> documents, SiteRenderingContext
siteRenderingContext, File outputDirectory)
@@ -611,15 +621,22 @@ public class DefaultSiteRenderer implements Renderer {
if (docRenderingContext != null
&& siteRenderingContext.isDeriveBreadcrumbsFromMenu()
&& siteModel != null
- && siteModel.getBody() != null
- && siteModel.getBody().getBreadcrumbs().isEmpty()) {
+ && siteModel.getBody() != null) {
List<LinkItem> derivedBreadcrumbs =
MenuBreadcrumbs.derive(siteModel.getMenus(),
docRenderingContext.getOutputPath());
if (!derivedBreadcrumbs.isEmpty()) {
+ // the menu trail follows the declared (usually inherited)
breadcrumbs, without repeating a link
+ List<LinkItem> declared = siteModel.getBody().getBreadcrumbs();
+ List<LinkItem> trail = new ArrayList<>(declared);
+ for (LinkItem derived : derivedBreadcrumbs) {
+ if (derived.getHref() == null || !containsHref(declared,
derived.getHref())) {
+ trail.add(derived);
+ }
+ }
// clone: the site model is shared across all documents of
this site rendering,
// and the derived trail is specific to this one document
siteModel = siteModel.clone();
- siteModel.getBody().setBreadcrumbs(derivedBreadcrumbs);
+ siteModel.getBody().setBreadcrumbs(trail);
}
}
context.put("site", siteModel);
diff --git
a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
index 3f55347..c244cff 100644
---
a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
+++
b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
@@ -175,13 +175,13 @@ public class SiteRenderingContext {
}
/**
- * If breadcrumbs should be derived from the site descriptor's menu
hierarchy for documents which
- * declare no explicit <code><breadcrumbs></code> element.
- * By default this is switched off: a document without an explicit
<code><breadcrumbs></code>
- * element then renders with an empty breadcrumb trail, as it always has.
+ * If breadcrumbs should be derived from the site descriptor's menu
hierarchy: the menus and menu items
+ * that contain the document follow the declared (usually inherited)
<code><breadcrumbs></code>,
+ * skipping a link that is already declared.
+ * By default this is switched off: a document then renders with the
declared breadcrumbs only, as it always has.
*
* @return true if breadcrumbs should be derived from the menu hierarchy.
- * @since 2.1.1
+ * @since 2.2.0
*/
public boolean isDeriveBreadcrumbsFromMenu() {
return deriveBreadcrumbsFromMenu;
@@ -191,7 +191,7 @@ public class SiteRenderingContext {
* Switch on/off deriving breadcrumbs from the site descriptor's menu
hierarchy.
*
* @param deriveBreadcrumbsFromMenu true to switch on breadcrumb
derivation.
- * @since 2.1.1
+ * @since 2.2.0
*/
public void setDeriveBreadcrumbsFromMenu(boolean
deriveBreadcrumbsFromMenu) {
this.deriveBreadcrumbsFromMenu = deriveBreadcrumbsFromMenu;
diff --git
a/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DeriveBreadcrumbsFromMenuTest.java
b/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DeriveBreadcrumbsFromMenuTest.java
index 71cf984..90570f2 100644
---
a/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DeriveBreadcrumbsFromMenuTest.java
+++
b/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DeriveBreadcrumbsFromMenuTest.java
@@ -21,6 +21,7 @@ package org.apache.maven.doxia.siterenderer;
import javax.inject.Inject;
import java.io.File;
+import java.util.Arrays;
import java.util.Collections;
import java.util.List;
@@ -114,12 +115,20 @@ class DeriveBreadcrumbsFromMenuTest {
assertTrue(siteModel.getBody().getBreadcrumbs().isEmpty());
}
+ private static LinkItem link(String name, String href) {
+ LinkItem link = new LinkItem();
+ link.setName(name);
+ link.setHref(href);
+ return link;
+ }
+
@Test
- void explicitBreadcrumbsWinOverDerivation() {
+ void derivedTrailFollowsDeclaredBreadcrumbs() {
SiteModel siteModel = siteModelWithMenu();
- LinkItem explicit = new LinkItem();
- explicit.setName("Explicit crumb");
-
siteModel.getBody().setBreadcrumbs(Collections.singletonList(explicit));
+ siteModel
+ .getBody()
+ .setBreadcrumbs(Arrays.asList(
+ link("Apache", "https://www.apache.org/"),
link("Maven", "https://maven.apache.org/")));
SiteRenderingContext siteRenderingContext = new SiteRenderingContext();
siteRenderingContext.setSiteModel(siteModel);
@@ -128,11 +137,40 @@ class DeriveBreadcrumbsFromMenuTest {
Context context =
siteRenderer.createDocumentVelocityContext(documentAt("guides/user/index"),
siteRenderingContext);
- // the declared breadcrumbs are used as-is, no derivation is
attempted, no clone is made
- assertSame(siteModel, context.get("site"));
+ // the inherited crumbs first, then the menu that contains the document
List<LinkItem> breadcrumbs = ((SiteModel)
context.get("site")).getBody().getBreadcrumbs();
- assertEquals(1, breadcrumbs.size());
- assertEquals("Explicit crumb", breadcrumbs.get(0).getName());
+ assertEquals(3, breadcrumbs.size());
+ assertEquals("Apache", breadcrumbs.get(0).getName());
+ assertEquals("Maven", breadcrumbs.get(1).getName());
+ assertEquals("Documentation", breadcrumbs.get(2).getName());
+ // the shared site model keeps its two declared crumbs
+ assertEquals(2, siteModel.getBody().getBreadcrumbs().size());
+ }
+
+ @Test
+ void derivedLinkAlreadyDeclaredIsNotRepeated() {
+ MenuItem chapter = new MenuItem();
+ chapter.setName("Guides");
+ chapter.setHref("guides/index.html");
+ MenuItem userGuide = new MenuItem();
+ userGuide.setName("User Guide");
+ userGuide.setHref("guides/user/index.html");
+ chapter.setItems(Collections.singletonList(userGuide));
+ SiteModel siteModel = siteModelWithMenu();
+
siteModel.getBody().getMenus().get(0).setItems(Collections.singletonList(chapter));
+
siteModel.getBody().setBreadcrumbs(Collections.singletonList(link("Guides",
"guides/index.html")));
+
+ SiteRenderingContext siteRenderingContext = new SiteRenderingContext();
+ siteRenderingContext.setSiteModel(siteModel);
+ siteRenderingContext.setDeriveBreadcrumbsFromMenu(true);
+
+ Context context =
+
siteRenderer.createDocumentVelocityContext(documentAt("guides/user/index"),
siteRenderingContext);
+
+ List<LinkItem> breadcrumbs = ((SiteModel)
context.get("site")).getBody().getBreadcrumbs();
+ assertEquals(2, breadcrumbs.size());
+ assertEquals("Guides", breadcrumbs.get(0).getName());
+ assertEquals("Documentation", breadcrumbs.get(1).getName());
}
@Test