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 ed083a8 Document the site features added in 2.2.0
ed083a8 is described below
commit ed083a8cddfea0c8d1a5cc9e4db054908308e4b8
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Fri Nov 13 21:05:18 2026 +0100
Document the site features added in 2.2.0
---
doxia-site-model/src/site/markdown/index.md | 16 ++++++++++++++++
doxia-site-renderer/src/site/markdown/index.md.vm | 14 ++++++++++++--
2 files changed, 28 insertions(+), 2 deletions(-)
diff --git a/doxia-site-model/src/site/markdown/index.md
b/doxia-site-model/src/site/markdown/index.md
index 033be58..ea1c62d 100644
--- a/doxia-site-model/src/site/markdown/index.md
+++ b/doxia-site-model/src/site/markdown/index.md
@@ -38,6 +38,22 @@ The following are generated from this model:
Site model can be merged from a parent `site.xml` into a child `site.xml`
using `SiteModelInheritanceAssembler`
([javadoc](./apidocs/org/apache/maven/doxia/site/inheritance/SiteModelInheritanceAssembler.html))
with its `DefaultSiteModelInheritanceAssembler` implementation
([source](https://github.com/apache/maven-doxia-sitetools/blob/master/doxia-site-model/src/main/java/org/apache/maven/doxia/site/inheritance/DefaultSiteModelInheritanceAssembler.java)).
+By default, the child's links and breadcrumbs are added to the parent's. Since
site descriptor 2.2.0, `combine.links="override"` and
`combine.breadcrumbs="override"` on the child's `<body>` keep only the child's
own entries; for breadcrumbs, the entry generated for the child project is left
out too, so an empty list stays empty:
+
+```xml
+<body combine.breadcrumbs="override">
+ <breadcrumbs>
+ <item name="My project" href="https://example.com/"/>
+ </breadcrumbs>
+</body>
+```
+
+`<site combine.self="override">` drops the whole parent descriptor.
+
+## Model versions
+
+A descriptor declares its model version in its namespace, for example
`http://maven.apache.org/SITE/2.2.0`. Since 2.2.0, reading a site or skin
descriptor that declares a newer model than this release supports logs a
warning naming both versions: the descriptor's unknown elements would otherwise
fail with less obvious parse errors. Older model versions are read without a
warning.
+
## Interpolation
Interpolation is not done here: see [ Doxia Integration
Tools](../doxia-integration-tools/) documentation for more details.
diff --git a/doxia-site-renderer/src/site/markdown/index.md.vm
b/doxia-site-renderer/src/site/markdown/index.md.vm
index 7b56fb2..24d05b5 100644
--- a/doxia-site-renderer/src/site/markdown/index.md.vm
+++ b/doxia-site-renderer/src/site/markdown/index.md.vm
@@ -29,10 +29,20 @@ under the License.
The Site Renderer handles the rendering of sites, assembling a common site
template (also called _a skin_) with a collection of documents.
-Documents can be dynamically generated with [Doxia Sink
API](/doxia/doxia/doxia-sink-api/), like Maven reports, or simply read from
static files written in [markup supported by Doxia
Parsers](/doxia/references/index.html), optionally preprocessed by
[Velocity](https://velocity.apache.org/engine/${velocityEngineVersion}) if
their file names end with `.vm`.
+Documents can be dynamically generated with [Doxia Sink
API](/doxia/doxia/doxia-sink-api/), like Maven reports, or simply read from
static files written in [markup supported by Doxia
Parsers](/doxia/references/index.html), optionally preprocessed by
[Velocity](https://velocity.apache.org/engine/${velocityEngineVersion}) if
their file names end with `.vm` (see below).

+${esc.h}${esc.h} Document sources
+
+Documents are read from one directory per markup format under each site
directory, for example `src/site/markdown` for Markdown and `src/site/apt` for
APT.
+
+Since 2.2.0, a caller can also switch on a shared `source` directory with
[`SiteRenderingContext.setSharedSourceDirectory(true)`](./apidocs/org/apache/maven/doxia/siterenderer/SiteRenderingContext.html).
Pages of any format can then live together in `src/site/source`, and the file
extension picks the parser: `index.md` is Markdown, `guide/usage.apt` is APT.
The format directories are still read, and a page found in both places fails
the build as a duplicate. The site descriptor stays in [...]
+
+${esc.h}${esc.h} Breadcrumbs from menus
+
+Since 2.2.0, a caller can switch on
[`SiteRenderingContext.setDeriveBreadcrumbsFromMenu(true)`](./apidocs/org/apache/maven/doxia/siterenderer/SiteRenderingContext.html).
The menu and the chain of menu items that contain the document being rendered
are then added after the breadcrumbs the site descriptor declares or inherits,
and a link that is already declared is not repeated. The document's own menu
item is left out, because skins print the page title after the breadcrumbs. A
menu item [...]
+
${esc.h}${esc.h} Doxia Site Skins
A default site template is included (see `default-site.vm`), but other
templates can be used at will, either as a standalone template or packaged in a
[**skin** artifact](../doxia-skin-model/).
@@ -43,7 +53,7 @@ Some documentation is available on [how to create a new
skin](/plugins/maven-sit
${esc.h}${esc.h} Velocity processing
-Site and documents with file names ending in `.vm` are processed by Velocity.
+Site and documents with file names ending in `.vm` are processed by Velocity.
A document can be named either way round: `index.md.vm` and, since 2.2.0,
`index.vm.md` are both Velocity templates for a Markdown page and render to
`index.html`. With the `.vm` first, editors open the file as Markdown. If a
page exists under both names, the build fails with a duplicate document error.
The Velocity context contains some variables related to rendering context that
you can use: