Derive breadcrumbs from the site descriptor menu hierarchy

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. `` says where a page sits in the navigation, and `` says where it sits in the trail:

```xml

```

Nothing keeps the two in step. Breadcrumb items are inherited 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.

## Where the code lives

The work belongs in [maven-doxia-sitetools](https://github.com/apache/maven-doxia-sitetools), not in this repository. This plugin holds no breadcrumb logic: the only occurrence of the word in `src/main` is a javadoc comment in `AbstractSiteDescriptorMojo`. Breadcrumb handling sits in `doxia-site-model`, and the existing inheritance behaviour that #1050, #674, and #701 describe is in `DefaultSiteModelInheritanceAssembler`. This plugin depends on doxia-sitetools through the `doxiaSitetoolsVersion` property, so its part is limited to exposing configuration and consuming a released version.

The issue stays here because that is where it was raised and where the affected sites are built. Move it if maven-doxia-sitetools is the better home for the implementation discussion.

## Proposal

Derive the breadcrumb trail from the menu hierarchy when the descriptor declares no `` element.

The behaviour would be as follows:

- Locate the page being rendered among the `` elements of the effective site descriptor.
- Build the trail from the `name` attributes of the enclosing `` elements and their ``.
- Resolve `ref`, `inherit`, and `inheritAsRef` on `` before walking the tree, so that `` and inherited menus contribute the same structure a reader sees in the navigation.
- Leave an explicit `` element alone, so existing sites render unchanged.

### Example

Given this descriptor:

```xml

```

Rendering `/doxia/architecture.html` derives the trail `Maven / Doxia / Architecture` from the enclosing `` and the nested `` chain, with no `` element present.

### Configuration

An opt-in parameter, defaulting to off, keeps the change inert for sites that don't want it:

```xml

org.apache.maven.plugins
maven-site-plugin

true

```

## Scope

A change of this shape covers the following:

- Deriving a trail from the menu hierarchy when no `` element is declared.
- Giving an explicit `` 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 runs. A breadcrumb depends on which page is rendering, but a site model is assembled per project, so the trail may not be computable in `SiteModelInheritanceAssembler` at all and may have to move into the renderer. `doxia-site-renderer` mentions breadcrumbs nowhere today, so this would be new ground there.
- What a page absent from every menu should render, given that the existing behaviour is an inherited trail rather than none.
- How a derived trail should combine with an inherited one in a multi-module build, since the two answer the same question from different sources.
- Whether the parameter should default to on in a major release once the behaviour 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.*

Start with DefaultSiteModelInheritanceAssembler and AbstractSiteDescriptorMojo, then inspect breadcrumb handling in doxia-site-model and the renderer in maven-doxia-sitetools. Establish where page-specific menu traversal belongs; done should include opt-in derivation, explicit breadcrumb precedence, menu references and inheritance, tests, and the configuration documentation.

Written by the indexing model from the issue text.