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>