slachiewicz opened a new issue, #1300: URL: https://github.com/apache/maven-site-plugin/issues/1300
The Doxia site moved into `maven-site` (apache/maven-site#1645), and pages under `/doxia/` lost a breadcrumb level along the way. https://maven.apache.org/doxia/index.html renders `Apache / Maven / Introduction`, where before the move it read `Apache / Maven / Doxia / Introduction`. Hervé Boutemy [called this out while planning the move](https://github.com/apache/maven-site/issues/1645#issuecomment-5340818720) and asked for the fix to land here: > the only aspect we're loosing is the breadcrumb in doxia-site = "Apache > Maven > Doxia > Introduction" in https://maven.apache.org/doxia/index.html will become "Apache > Maven > Introduction" > > notice: detecting breadcrumbs from menu hierarchy is a feature I want us to add to Maven Site Plugin one day, this will be the right time to work together on this, that will add the breadcrumb back in the future (TBD) ## The problem A site descriptor states the same structure twice. `<menu>` says where a page sits in the navigation, and `<breadcrumbs>` says where it sits in the trail: ```xml <body> <breadcrumbs> <item name="Doxia" href="https://maven.apache.org/doxia/index.html"/> </breadcrumbs> <menu name="Doxia"> <item name="Introduction" href="index.html"/> </menu> </body> ``` Nothing keeps the two in step. The plugin inherits `<breadcrumbs>` items from parent projects, which covers part of the multi-module case and carries its own difficulties (#1050, #674, #701), but no mechanism derives a trail from the menu hierarchy in the descriptor that renders the page. When a site is restructured, as in the Doxia move, the menu changes and the breadcrumb stays where it was. ## Proposal Derive the breadcrumb trail from the menu hierarchy when the descriptor declares no `<breadcrumbs>` element. The plugin would do the following: - Locate the page being rendered among the `<item>` elements of the effective site descriptor. - Build the trail from the `name` attributes of the enclosing `<item>` elements and their `<menu>`. - Resolve `ref`, `inherit`, and `inheritAsRef` on `<menu>` before walking the tree, so that `<menu ref="modules"/>` and inherited menus contribute the same structure a reader sees in the navigation. - Leave an explicit `<breadcrumbs>` element alone, so existing sites render unchanged. ### Example Given this descriptor: ```xml <site> <body> <menu name="Maven"> <item name="Documentation" href="/docs/index.html"/> <item name="Doxia" href="/doxia/index.html"> <item name="Introduction" href="/doxia/index.html"/> <item name="Architecture" href="/doxia/architecture.html"/> </item> </menu> </body> </site> ``` Rendering `/doxia/architecture.html` derives the trail `Maven / Doxia / Architecture` from the enclosing `<menu name>` and the nested `<item name>` chain, with no `<breadcrumbs>` element present. ### Configuration An opt-in parameter, defaulting to off, keeps the change inert for sites that don't want it: ```xml <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <configuration> <generateBreadcrumbsFromMenus>true</generateBreadcrumbsFromMenus> </configuration> </plugin> ``` ## Scope A change of this shape covers the following: - Deriving a trail from the menu hierarchy when no `<breadcrumbs>` element is declared. - Giving an explicit `<breadcrumbs>` element precedence over a derived trail. - Handling menu references and inheritance in multi-module builds. - Unit and integration tests for the derivation and for the precedence rule. - Documentation in [Configuring the site descriptor](https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html#Breadcrumbs). ## Open questions - Where the derivation belongs: the plugin, or Doxia Sitetools alongside the existing descriptor inheritance. - What a page absent from every menu should render, given that the current behavior is an inherited trail rather than none. - Whether the parameter should default to on in a major release once the behavior settles. ## Related issues - apache/maven-site#1645 — Move the Doxia site into maven-site. Closed; the move is what removed the level. - #1050 (MSITE-910) — Allow skipping auto-generated breadcrumb item for parent module. Open. - #674 (MSITE-582) — Make it possible to remove breadcrumbs in child projects again. Closed. - #701 (MSITE-608) — Aggregating breadcrumb behavior disappears in the presence of a menu in the parent. Closed. *This issue was created with AI assistance.* -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
