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 896dafc  Refresh the Sitetools site for 2.2.0 and document the SCM 
context module
896dafc is described below

commit 896dafc6bfe3f19527f8e96a4090e108845328d9
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 21:46:46 2026 +0000

    Refresh the Sitetools site for 2.2.0 and document the SCM context module
    
    The maven-site-plugin Javadoc link is absolute because Doxia encodes the 
fragment of a site-relative link, which breaks the (java.util.Locale) anchor.
---
 doxia-integration-tools/src/site/markdown/index.md |  4 +-
 doxia-integration-tools/src/site/markdown/usage.md | 90 +++++++++++++++-------
 doxia-site-model/src/site/markdown/index.md        |  2 +-
 doxia-site-renderer/src/site/markdown/index.md.vm  |  4 +-
 .../src/site/markdown/index.md.vm                  | 70 +++++++++++++++++
 doxia-site-scm-context/src/site/site.xml           |  2 +-
 src/site/markdown/index.md                         | 32 ++++++--
 7 files changed, 164 insertions(+), 40 deletions(-)

diff --git a/doxia-integration-tools/src/site/markdown/index.md 
b/doxia-integration-tools/src/site/markdown/index.md
index 09311d6..0710811 100644
--- a/doxia-integration-tools/src/site/markdown/index.md
+++ b/doxia-integration-tools/src/site/markdown/index.md
@@ -29,11 +29,11 @@ under the License.
 
 This shared component has some utilities that are useful when integrating 
Doxia in Maven, mainly for site generation and report creation.
 
-The main entry point is the 
[SiteTool](./apidocs/org/apache/maven/doxia/tools/SiteTool.html) Plexus 
component.
+The main entry point is the 
[SiteTool](./apidocs/org/apache/maven/doxia/tools/SiteTool.html) JSR-330 
component.
 
 ## Usage
 
-Instructions on how to use the integration of Doxia in Maven can be found 
[here](./usage.html).
+[Using the SiteTool in a Mojo](./usage.html) shows how to read the site 
descriptor of a project from your own plugin.
 
 ## `site.xml` Model Interpolation
 
diff --git a/doxia-integration-tools/src/site/markdown/usage.md 
b/doxia-integration-tools/src/site/markdown/usage.md
index cf5ec73..0f396b2 100644
--- a/doxia-integration-tools/src/site/markdown/usage.md
+++ b/doxia-integration-tools/src/site/markdown/usage.md
@@ -27,41 +27,73 @@ under the License.
 
 # Using the SiteTool in a Mojo
 
-```unknown
-...
+`SiteTool` is a JSR-330 component. Inject it into your Mojo's constructor, 
then use it to read the site descriptor
+of the current project with inheritance and interpolation applied, the same 
way the Maven Site Plugin does:
+
+```java
+import javax.inject.Inject;
+
+import java.io.File;
+import java.util.List;
+import java.util.Locale;
+
+import org.apache.maven.doxia.site.SiteModel;
 import org.apache.maven.doxia.tools.SiteTool;
-import org.apache.maven.plugins.annotations.Component;
+import org.apache.maven.doxia.tools.SiteToolException;
+import org.apache.maven.execution.MavenSession;
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugin.MojoExecutionException;
 import org.apache.maven.plugins.annotations.Mojo;
-...
-
-/**
- * Your own mojo.
- */
-@Mojo( name = "your-own" )
-public class YourOwnMojo extends AbstractMojo
-{
-    ...
-
-    /**
-     * SiteTool.
-     */
-    @Component
-    protected SiteTool siteTool;
-
-    ...
-
-    public someMethod()
-    {
-        List localesList = siteTool.getSiteLocales( locales );
-        String relativePath = siteTool.getRelativePath( "C:/foo/child",
-                                                        "C:/foo/master" );
-        ...
+import org.apache.maven.plugins.annotations.Parameter;
+import org.apache.maven.project.MavenProject;
+
+@Mojo(name = "your-own")
+public class YourOwnMojo extends AbstractMojo {
+
+    @Parameter(defaultValue = "${session}", readonly = true, required = true)
+    private MavenSession session;
+
+    @Parameter(defaultValue = "${project}", readonly = true, required = true)
+    private MavenProject project;
+
+    @Parameter(defaultValue = "${project.basedir}/src/site", required = true)
+    private File siteDirectory;
+
+    @Parameter(property = "locales")
+    private String locales;
+
+    private final SiteTool siteTool;
+
+    @Inject
+    public YourOwnMojo(SiteTool siteTool) {
+        this.siteTool = siteTool;
     }
 
-    ...
+    @Override
+    public void execute() throws MojoExecutionException {
+        try {
+            for (Locale locale : siteTool.getSiteLocales(locales)) {
+                SiteModel siteModel = siteTool.getSiteModel(
+                        siteDirectory,
+                        locale,
+                        session.getRequest(),
+                        project,
+                        session.getProjects(),
+                        session.getRepositorySession(),
+                        project.getRemoteProjectRepositories());
+                getLog().info("Site " + siteModel.getName() + " for locale " + 
locale);
+            }
+        } catch (SiteToolException e) {
+            throw new MojoExecutionException("Cannot read the site 
descriptor", e);
+        }
+    }
 }
 ```
 
+`getSiteLocales(null)` returns only `Locale.ROOT`, the default site locale. 
`getRelativePath(to, from)` computes a
+relative link between two locations and treats `from` as a directory.
+
 ## References
 
-1. [SiteTool API](./apidocs/org/apache/maven/doxia/tools/SiteTool.html)
+- [SiteTool API](./apidocs/org/apache/maven/doxia/tools/SiteTool.html)
+- [How the site descriptor is 
interpolated](./index.html#site.xml_Model_Interpolation)
diff --git a/doxia-site-model/src/site/markdown/index.md 
b/doxia-site-model/src/site/markdown/index.md
index ea1c62d..a7d7af1 100644
--- a/doxia-site-model/src/site/markdown/index.md
+++ b/doxia-site-model/src/site/markdown/index.md
@@ -26,7 +26,7 @@ under the License.
 
 # Doxia Sitetool Site Model
 
-This is strictly the model for Doxia Sitetool Site Model, used in 
maven-site-plugin as `site.xml` to inject parameters into site template: see 
[Doxia Site Renderer](../doxia-site-renderer/) for more details on site 
rendering.
+This is the model of the site descriptor, `site.xml`, which the Maven Site 
Plugin reads to build menus, breadcrumbs and other decoration around the pages: 
see [Doxia Site Renderer](../doxia-site-renderer/) for how a site is rendered. 
To write a `site.xml`, start with the [site descriptor 
guide](/guides/mini/guide-site-descriptor.html); the [descriptor 
reference](./site.html) lists every element.
 
 The following are generated from this model:
 
diff --git a/doxia-site-renderer/src/site/markdown/index.md.vm 
b/doxia-site-renderer/src/site/markdown/index.md.vm
index 24d05b5..cdb3574 100644
--- a/doxia-site-renderer/src/site/markdown/index.md.vm
+++ b/doxia-site-renderer/src/site/markdown/index.md.vm
@@ -134,7 +134,7 @@ When `doxia-site-renderer` is used by `maven-site-plugin`, 
the following templat
 
|`project`|[`MavenProject`](/ref/current/maven-core/apidocs/org/apache/maven/project/MavenProject.html)|The
 current project.|
 |_project properties_|`String`|Properties defined in POM are directly 
available.|
 
-See 
[`AbstractSiteRenderingMojo.createSiteRenderingContext(...)`](/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.html${esc.hash}createSiteRenderingContext-java.util.Locale-)
 source for more details.
+See 
[`AbstractSiteRenderingMojo.createSiteRenderingContext(...)`](https://maven.apache.org/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.html${esc.hash}createSiteRenderingContext(java.util.Locale))
 source for more details.
 
 ${esc.h}${esc.h}# Site Template
 
@@ -150,5 +150,5 @@ When Velocity is processing the site template (be it from 
skin or local template
 |`title`|`String`|The title of the document, including the project or site 
name.|
 
|`docRenderingContext`|[`DocumentRenderingContext`](./apidocs/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.html)|(since
 1\.8) The document rendering context.|
 
-See 
[`DefaultSiteRenderer.createSiteTemplateVelocityContext(...)`](https://github.com/apache/maven-doxia-sitetools/blob/master/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java${esc.hash}L654)
 source for more details.
+See 
[`DefaultSiteRenderer.createSiteTemplateVelocityContext(...)`](https://github.com/apache/maven-doxia-sitetools/blob/master/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java)
 source for more details.
 
diff --git a/doxia-site-scm-context/src/site/markdown/index.md.vm 
b/doxia-site-scm-context/src/site/markdown/index.md.vm
new file mode 100644
index 0000000..9b99a67
--- /dev/null
+++ b/doxia-site-scm-context/src/site/markdown/index.md.vm
@@ -0,0 +1,70 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Doxia Sitetools - SCM Context
+
+This optional module adds the date and author of the last change to each page, 
read from the version control system
+of the site sources. A skin can then show "Last updated" information per page 
instead of one publish date for the
+whole site.
+
+${esc.h}${esc.h} Setup
+
+Add the module to the dependencies of the Maven Site Plugin. It needs Maven 
Site Plugin 3.22.0 or later, the first
+release built on Doxia Sitetools 2.1.0.
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-site-plugin</artifactId>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven.doxia</groupId>
+      <artifactId>doxia-site-scm-context</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+  </dependencies>
+</plugin>
+```
+
+${esc.h}${esc.h} What it adds
+
+For each rendered document the module adds two variables to the Velocity 
context:
+
+| Variable | Type | Description |
+|:---|:---|:---|
+| `scmModifiedDate` | `Date` | The date of the last commit that changed the 
source file. |
+| `scmModifiedAuthor` | `String` | The author of that commit. |
+
+When a page does not set an author or a date itself, the site template 
variables `authors` and `documentDate` fall
+back to these values; see the [Site Template 
section](../doxia-site-renderer/index.html${esc.hash}Site_Template) of the
+Site Renderer. Whether and how the values appear on the page is up to the skin.
+
+${esc.h}${esc.h} How it works
+
+The module is a 
[`ContextCustomizer`](../doxia-site-renderer/apidocs/org/apache/maven/doxia/siterenderer/ContextCustomizer.html).
+On the first document it looks for a working copy in the site root directory 
and then in its parent directories,
+using the [Maven SCM](/scm/) providers for Git, Mercurial and Subversion. It 
then asks the SCM for the last change of
+each source file, one query per document. If no working copy is found, nothing 
is added and the site renders as
+before.
+
+A shallow Git clone has no history beyond its last commits, so the dates would 
be wrong; the module logs a warning
+when the repository is shallow. On CI, check out the full history, for example 
with `fetch-depth: 0` in GitHub
+Actions' `actions/checkout`.
+
+Generated documents, such as reports, have no source file and get no SCM 
values.
diff --git a/doxia-site-scm-context/src/site/site.xml 
b/doxia-site-scm-context/src/site/site.xml
index ee641d2..5208dc8 100644
--- a/doxia-site-scm-context/src/site/site.xml
+++ b/doxia-site-scm-context/src/site/site.xml
@@ -23,7 +23,7 @@
 
 <site xmlns="http://maven.apache.org/SITE/2.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
       xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 
https://maven.apache.org/xsd/site-2.0.0.xsd";
-      name="Site Model">
+      name="SCM Context">
 
   <body>
 
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 89dfe05..a27e191 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -23,20 +23,42 @@ author:
  */
 -->
 
+
 # Doxia Sitetools
 
-Doxia Sitetools is an extension of [base Doxia component](../doxia) that 
generates: **HTML sites**, adding site (header, footer, navigation bar, menu, 
...) to content that was generated by Doxia: a site is defined in a **site 
skin**.
+Doxia Sitetools turns single documents into a website. [Doxia](../doxia/) 
converts each page from Markdown, APT or
+another format into HTML; Sitetools adds what a site needs around it: the 
menus, breadcrumbs, header and footer
+described in `site.xml`, and a skin that gives the pages their look. The
+[Maven Site Plugin](/plugins/maven-site-plugin/) uses Sitetools for every `mvn 
site` run.
+
+If you build a site with Maven, the user guides are the place to start:
+
+- [Creating a site](/guides/mini/guide-site.html)
+- [Configuring the site descriptor](/guides/mini/guide-site-descriptor.html), 
`site.xml`
+- [Building a site for a multi-module 
project](/guides/mini/guide-multimodule-site.html)
+- [Choosing a skin](/skins/) or [creating your 
own](/plugins/maven-site-plugin/examples/creatingskins.html)
+
+The pages here document the components themselves, for skin authors and for 
developers of plugins that render
+documents.
+
+| Module | What it does |
+|---|---|
+| [Site Renderer](doxia-site-renderer/index.html) | Renders documents and 
reports into a skin. Documents the Velocity variables available to pages and 
skins. |
+| [Site Model](doxia-site-model/index.html) | The `site.xml` model, its 
[reference](doxia-site-model/site.html), and how a child descriptor inherits 
from its parent. |
+| [Skin Model](doxia-skin-model/index.html) | The `skin.xml` model that a skin 
declares. |
+| [Integration Tools](doxia-integration-tools/index.html) | `SiteTool`, which 
finds, inherits and interpolates the site descriptor of a Maven project. |
+| [SCM Context](doxia-site-scm-context/index.html) | Optional: adds the last 
change date and author of each page from Git or another SCM. |
 
-In addition, Doxia Sitetools processes files with extra `.vm` extension with 
[Velocity](http://velocity.apache.org/).
+The following diagram shows how the modules depend on each other.
 
-<img src="images/doxia-sitetools-deps.png" border="0" 
usemap="#Doxia_sitetools_dependencies" alt="Doxia Sitetools Dependencies"/>
+<img src="images/doxia-sitetools-deps.png" 
usemap="#Doxia_sitetools_dependencies" alt="Doxia Sitetools Dependencies"/>
 <map name="Doxia_sitetools_dependencies" id="Doxia_sitetools_dependencies">
           <area shape="rect" coords="133,63,274,97"   
href="doxia-site-renderer/index.html"       alt="Doxia Site Renderer"/>
           <area shape="rect" coords="2,119,162,153"   
href="doxia-integration-tools/index.html"   alt="Doxia Integration Tools"/>
           <area shape="rect" coords="32,232,199,267"  
href="doxia-site-model/index.html"          alt="Doxia Site Model"/>
           <area shape="rect" coords="207,232,324,267" 
href="doxia-skin-model/index.html"          alt="Doxia Skin Model"/>
-          <area shape="rect" coords="288,123,444,159" 
href="http://codehaus-plexus.github.io/plexus-velocity/";        alt="Plexus 
Velocity"/>
-          <area shape="rect" coords="318,180,414,214" 
href="http://velocity.apache.org";                               alt="Velocity"/>
+          <area shape="rect" coords="288,123,444,159" 
href="https://codehaus-plexus.github.io/plexus-velocity/";        alt="Plexus 
Velocity"/>
+          <area shape="rect" coords="318,180,414,214" 
href="https://velocity.apache.org/";                               
alt="Velocity"/>
           <area shape="rect" coords="134,301,274,337" 
href="/doxia/doxia/doxia-modules/doxia-module-xhtml5/index.html" alt="Doxia 
Module XHTML5"/>
           <area shape="rect" coords="114,288,252,353" 
href="/doxia/doxia/doxia-modules/index.html" alt="Doxia Modules"/>
         </map> 

Reply via email to