slachiewicz opened a new pull request, #684: URL: https://github.com/apache/maven-doxia-sitetools/pull/684
Restores a breadcrumb level that the Doxia site consolidation removed, and makes the trail derivable from structure the descriptor already carries. ## Why `https://maven.apache.org/doxia/index.html` renders `Apache / Maven / Introduction`. Before the Doxia site moved into `maven-site` (apache/maven-site#1645) it read `Apache / Maven / Doxia / Introduction`. Hervé Boutemy [predicted the loss while planning the move](https://github.com/apache/maven-site/issues/1645#issuecomment-5340818720) and asked for menu-derived breadcrumbs as the fix. More generally, a site descriptor states its structure twice. `<menu>` says where a page sits in the navigation and `<breadcrumbs>` says where it sits in the trail, with nothing keeping the two in step. Requested in apache/maven-site-plugin#1300. ## What A new opt-in flag `SiteRenderingContext.deriveBreadcrumbsFromMenu`, default `false`. When it is set and the site declares no explicit `<breadcrumbs>`, the renderer locates the current document among the `<menu><item href>` values and builds a trail from the enclosing menu's name and the chain of enclosing `<item>` names. Three decisions worth reviewing: **Per document, not during model assembly.** A breadcrumb depends on which page is rendering, and `SiteModelInheritanceAssembler` runs once per project with no notion of a current document. The derivation therefore lives in `DefaultSiteRenderer.createDocumentVelocityContext`, the one place holding a `DocumentRenderingContext`. The shared `SiteModel` is cloned before the trail is set, so one document's breadcrumbs cannot leak into another's. **Ancestors only, excluding the matched item.** Skins render the page title after the breadcrumbs, so including the matched item would print the page name twice. On the example above this yields `Apache / Maven / Doxia` with `Introduction` supplied by the skin, reproducing the pre-move trail exactly. **Href matching is deliberately literal.** It normalises a single leading `/` or `./`, and rejects external links via the existing `SiteUtils.isLink` plus anything carrying `#` or `?`. `DocumentRenderingContext.getOutputPath()` is documented as relative to the site root and the descriptors in this repository are written the same way. Menu hrefs written relative to the current page would not match, and would render as they do today rather than incorrectly. ## Compatibility With the flag off, `createDocumentVelocityContext` puts the same `SiteModel` instance into the Velocity context as before: no clone, no walk, no computation. An explicit `<breadcrumbs>` element always wins over derivation, so existing sites are unaffected whether or not the flag is set. ## Assumption a reviewer should check `ref`, `inherit`, and `inheritAsRef` on `<menu>` are assumed to be resolved before the model reaches `SiteRenderingContext`, as `DefaultSiteTool` does when maven-site-plugin invokes the renderer. If that ordering does not hold, an unresolved `ref` menu has no items, derivation finds nothing, and the page renders as it does today — the failure mode is a missing breadcrumb, not a wrong one. This has not been confirmed against an end-to-end site build, which needs the maven-site-plugin side. The plugin-facing parameter name in apache/maven-site-plugin#1300 is `generateBreadcrumbsFromMenus`, which should be reconciled with the renderer flag name before either ships. ## Tests `MenuBreadcrumbsTest` covers the derivation algorithm: nested item chains, an explicit trail winning, a page in no menu, external and fragment hrefs, and empty menus. `DeriveBreadcrumbsFromMenuTest` wires the flag through `createDocumentVelocityContext` on a real injected `DefaultSiteRenderer` and asserts the flag-off path leaves the model instance untouched. Verified: `mvn -o verify` → BUILD SUCCESS, all six modules, `Tests run: 31, Failures: 0, Errors: 0` in doxia-site-renderer and the pre-existing `SiteModelInheritanceAssemblerTest` (25 tests) unchanged. --- Following this checklist to help us incorporate your contribution quickly and easily: - [x] Your pull request should address just one issue, without pulling in other changes. - [x] Write a pull request description that is detailed enough to understand what the pull request does, how, and why. - [x] Each commit in the pull request should have a meaningful subject line and body. Note that commits might be squashed by a maintainer on merge. - [x] Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible but is a best-practice. - [x] Run `mvn verify` to make sure basic checks pass. A more thorough check will be performed on your pull request automatically. - [ ] You have run the integration tests successfully (`mvn -Prun-its verify`). The `run-its` profile exists only in `doxia-site-scm-context`, which this change does not touch. If your pull request is about ~20 lines of code you don't need to sign an [Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf) if you are unsure please ask on the developers list. To make clear that you license your contribution under the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0) you have to acknowledge this by using the following check-box. - [ ] I hereby declare this contribution to be licenced under the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0) - [ ] In any other case, please file an [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf). *This change 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]
