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).
 
 ![](doxia-site-renderer.png)
 
+${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:
 

Reply via email to