You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2026/04/18 09:38:17 UTC
(maven-site-plugin) branch master updated: Allow to give alternative source directories for sites
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 1b3cff68 Allow to give alternative source directories for sites
1b3cff68 is described below
commit 1b3cff68bcfe20f11dd9f9b7a94d7c91bc9e5768
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Wed Mar 11 15:16:43 2026 +0100
Allow to give alternative source directories for sites
Add ITs for verifying edit link
This relates to
https://github.com/apache/maven-doxia-sitetools/issues/277
---
pom.xml | 4 +-
.../editable-pages-alt-source/invoker.properties | 18 ++++
src/it/projects/editable-pages-alt-source/pom.xml | 91 ++++++++++++++++++++
.../src/site/markdown/ignore.txt | 21 +++++
.../src/site/markdown/markdown.md | 33 ++++++++
.../editable-pages-alt-source/src/site/site.xml | 46 ++++++++++
.../editable-pages-alt-source/verify.groovy | 33 ++++++++
src/it/projects/editable-pages/invoker.properties | 18 ++++
src/it/projects/editable-pages/pom.xml | 56 +++++++++++++
.../editable-pages/src/site/markdown/ignore.txt | 21 +++++
.../editable-pages/src/site/markdown/markdown.md | 33 ++++++++
src/it/projects/editable-pages/src/site/site.xml | 46 ++++++++++
src/it/projects/editable-pages/verify.groovy | 33 ++++++++
.../site/render/AbstractSiteRenderingMojo.java | 26 ++++--
.../site/render/ReportDocumentRenderer.java | 8 +-
src/site/markdown/examples/creating-content.md.vm | 2 +
src/site/markdown/examples/filtering-content.md | 98 ++++++++++++++++++++++
src/site/site.xml | 1 +
18 files changed, 574 insertions(+), 14 deletions(-)
diff --git a/pom.xml b/pom.xml
index 50e395b7..c766f2fe 100644
--- a/pom.xml
+++ b/pom.xml
@@ -29,7 +29,7 @@ under the License.
</parent>
<artifactId>maven-site-plugin</artifactId>
- <version>3.21.1-SNAPSHOT</version>
+ <version>3.22.0-SNAPSHOT</version>
<packaging>maven-plugin</packaging>
<name>Apache Maven Site Plugin</name>
@@ -199,7 +199,7 @@ under the License.
<!-- for dependencies -->
<jettyVersion>9.4.58.v20250814</jettyVersion>
<doxiaVersion>2.0.0</doxiaVersion>
- <doxiaSitetoolsVersion>2.0.0</doxiaSitetoolsVersion>
+ <doxiaSitetoolsVersion>2.1.0</doxiaSitetoolsVersion>
<wagonVersion>3.5.3</wagonVersion>
<slf4jVersion>1.7.36</slf4jVersion>
<!-- for ITs -->
diff --git a/src/it/projects/editable-pages-alt-source/invoker.properties b/src/it/projects/editable-pages-alt-source/invoker.properties
new file mode 100644
index 00000000..2e27904f
--- /dev/null
+++ b/src/it/projects/editable-pages-alt-source/invoker.properties
@@ -0,0 +1,18 @@
+# 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.
+
+invoker.goals = package site
diff --git a/src/it/projects/editable-pages-alt-source/pom.xml b/src/it/projects/editable-pages-alt-source/pom.xml
new file mode 100644
index 00000000..444f3682
--- /dev/null
+++ b/src/it/projects/editable-pages-alt-source/pom.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.apache.maven.plugins.site.its</groupId>
+ <artifactId>editable-pages-alt-source</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <name>Edit Link Alternative Source IT</name>
+
+ <properties>
+ <property-project-version>@project.version@</property-project-version>
+ <fluidoSkinVersion>@fluidoSkinVersion@</fluidoSkinVersion>
+ <project.build.outputTimestamp>@project.build.outputTimestamp@</project.build.outputTimestamp>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+ <myProperty>myValue</myProperty>
+ </properties>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>@project.version@</version>
+ <configuration>
+ <generateReports>true</generateReports>
+ <relativizeDecorationLinks>false</relativizeDecorationLinks>
+ <siteDirectory>${project.build.directory}/site-src</siteDirectory>
+ <alternativeSiteSourceDirectories>${basedir}/src/site</alternativeSiteSourceDirectories>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ <plugins>
+ <plugin>
+ <!-- prepare site content by filtering ${project.*} values -->
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>filter-site</id>
+ <phase>pre-site</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+ <configuration>
+ <outputDirectory>${project.build.directory}/site-src</outputDirectory>
+ <resources>
+ <resource>
+ <directory>src/site</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ <execution>
+ <id>default-testResources</id>
+ <configuration>
+ <!-- copy .gitignore as well -->
+ <addDefaultExcludes>false</addDefaultExcludes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
diff --git a/src/it/projects/editable-pages-alt-source/src/site/markdown/ignore.txt b/src/it/projects/editable-pages-alt-source/src/site/markdown/ignore.txt
new file mode 100644
index 00000000..d350e5df
--- /dev/null
+++ b/src/it/projects/editable-pages-alt-source/src/site/markdown/ignore.txt
@@ -0,0 +1,21 @@
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Markdown
diff --git a/src/it/projects/editable-pages-alt-source/src/site/markdown/markdown.md b/src/it/projects/editable-pages-alt-source/src/site/markdown/markdown.md
new file mode 100644
index 00000000..545c9835
--- /dev/null
+++ b/src/it/projects/editable-pages-alt-source/src/site/markdown/markdown.md
@@ -0,0 +1,33 @@
+title: Markdown Title Metadata
+author: Author Metadata
+date: Date Metadata
+description: Markdown description metadata, not known from Doxia API as title, author and date are
+
+<!---
+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.
+-->
+
+Markdown ${myProperty}
+=====================
+
+Subsection
+----------
+
+This is a subsection.
+
+Content for verify.groovy
diff --git a/src/it/projects/editable-pages-alt-source/src/site/site.xml b/src/it/projects/editable-pages-alt-source/src/site/site.xml
new file mode 100644
index 00000000..c39e8d03
--- /dev/null
+++ b/src/it/projects/editable-pages-alt-source/src/site/site.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<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="${project.name}">
+ <skin>
+ <groupId>org.apache.maven.skins</groupId>
+ <artifactId>maven-fluido-skin</artifactId>
+ <version>${fluidoSkinVersion}</version>
+ </skin>
+
+ <custom>
+ <fluidoSkin>
+ <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+ </fluidoSkin>
+ </custom>
+
+ <publishDate position="right" />
+ <version position="right" />
+ <edit>https://github.com/apache/maven-site-plugin/tree/master/</edit>
+
+ <body>
+ <breadcrumbs>
+ <item name="Editable Pages" href="index.html" />
+ </breadcrumbs>
+ </body>
+</site>
diff --git a/src/it/projects/editable-pages-alt-source/verify.groovy b/src/it/projects/editable-pages-alt-source/verify.groovy
new file mode 100644
index 00000000..62a8a757
--- /dev/null
+++ b/src/it/projects/editable-pages-alt-source/verify.groovy
@@ -0,0 +1,33 @@
+
+/*
+ * 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.
+ */
+
+def page = new File( basedir, 'target/site/markdown.html' )
+assert page.exists() : "$page must have been generated"
+def content = page.text
+
+assert content.contains( '<a href="https://github.com/apache/maven-site-plugin/tree/master/src/site/markdown/markdown.md"><img src="./images/accessories-text-editor.png" alt="Edit" /></a>' ) : 'Found invalid edit link'
+assert content.contains( '<h1>Markdown myValue</h1>' ) : 'Found invalid headline'
+
+
+page = new File( basedir, 'target/site/index.html' )
+assert page.exists() : "$page must have been generated"
+content = page.text
+
+assert !content.contains( '<img src="./images/accessories-text-editor.png" alt="Edit" />' ) : 'Found edit link for report that should not have it'
diff --git a/src/it/projects/editable-pages/invoker.properties b/src/it/projects/editable-pages/invoker.properties
new file mode 100644
index 00000000..2e27904f
--- /dev/null
+++ b/src/it/projects/editable-pages/invoker.properties
@@ -0,0 +1,18 @@
+# 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.
+
+invoker.goals = package site
diff --git a/src/it/projects/editable-pages/pom.xml b/src/it/projects/editable-pages/pom.xml
new file mode 100644
index 00000000..90a0bf82
--- /dev/null
+++ b/src/it/projects/editable-pages/pom.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.apache.maven.plugins.site.its</groupId>
+ <artifactId>editable-pages</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <name>Edit Link IT</name>
+
+ <properties>
+ <property-project-version>@project.version@</property-project-version>
+ <fluidoSkinVersion>@fluidoSkinVersion@</fluidoSkinVersion>
+ <project.build.outputTimestamp>@project.build.outputTimestamp@</project.build.outputTimestamp>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+ </properties>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>@project.version@</version>
+ <configuration>
+ <generateReports>true</generateReports>
+ <relativizeDecorationLinks>false</relativizeDecorationLinks>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ </build>
+
+</project>
diff --git a/src/it/projects/editable-pages/src/site/markdown/ignore.txt b/src/it/projects/editable-pages/src/site/markdown/ignore.txt
new file mode 100644
index 00000000..d350e5df
--- /dev/null
+++ b/src/it/projects/editable-pages/src/site/markdown/ignore.txt
@@ -0,0 +1,21 @@
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Markdown
diff --git a/src/it/projects/editable-pages/src/site/markdown/markdown.md b/src/it/projects/editable-pages/src/site/markdown/markdown.md
new file mode 100644
index 00000000..7478a523
--- /dev/null
+++ b/src/it/projects/editable-pages/src/site/markdown/markdown.md
@@ -0,0 +1,33 @@
+title: Markdown Title Metadata
+author: Author Metadata
+date: Date Metadata
+description: Markdown description metadata, not known from Doxia API as title, author and date are
+
+<!---
+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.
+-->
+
+Markdown Test
+=====================
+
+Subsection
+----------
+
+This is a subsection.
+
+Content for verify.groovy
diff --git a/src/it/projects/editable-pages/src/site/site.xml b/src/it/projects/editable-pages/src/site/site.xml
new file mode 100644
index 00000000..c39e8d03
--- /dev/null
+++ b/src/it/projects/editable-pages/src/site/site.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<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="${project.name}">
+ <skin>
+ <groupId>org.apache.maven.skins</groupId>
+ <artifactId>maven-fluido-skin</artifactId>
+ <version>${fluidoSkinVersion}</version>
+ </skin>
+
+ <custom>
+ <fluidoSkin>
+ <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+ </fluidoSkin>
+ </custom>
+
+ <publishDate position="right" />
+ <version position="right" />
+ <edit>https://github.com/apache/maven-site-plugin/tree/master/</edit>
+
+ <body>
+ <breadcrumbs>
+ <item name="Editable Pages" href="index.html" />
+ </breadcrumbs>
+ </body>
+</site>
diff --git a/src/it/projects/editable-pages/verify.groovy b/src/it/projects/editable-pages/verify.groovy
new file mode 100644
index 00000000..9c360124
--- /dev/null
+++ b/src/it/projects/editable-pages/verify.groovy
@@ -0,0 +1,33 @@
+
+/*
+ * 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.
+ */
+
+def page = new File( basedir, 'target/site/markdown.html' )
+assert page.exists() : "$page must have been generated"
+def content = page.text
+
+assert content.contains( '<a href="https://github.com/apache/maven-site-plugin/tree/master/src/site/markdown/markdown.md"><img src="./images/accessories-text-editor.png" alt="Edit" /></a>' ) : 'Found invalid edit link'
+assert content.contains( '<h1>Markdown Test</h1>' ) : 'Found invalid headline'
+
+
+page = new File( basedir, 'target/site/index.html' )
+assert page.exists() : "$page must have been generated"
+content = page.text
+
+assert !content.contains( '<img src="./images/accessories-text-editor.png" alt="Edit" />' ) : 'Found edit link for report that should not have it'
diff --git a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java
index 72270446..0eeb3b75 100644
--- a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java
@@ -100,13 +100,22 @@ public abstract class AbstractSiteRenderingMojo extends AbstractSiteDescriptorMo
* build time mean).
* This directory is expected to have the same structure as <code>siteDirectory</code>
* (ie. one directory per Doxia-source-supported markup types).
- *
- * todo should we deprecate in favour of reports directly using Doxia Sink API, without this Doxia source
- * intermediate step?
+ * This is never editable.
*/
@Parameter(alias = "workingDirectory", defaultValue = "${project.build.directory}/generated-site")
protected File generatedSiteDirectory;
+ /**
+ * Optional list of source directories to be used instead of {@link #siteDirectory} for rendering edit URLs.
+ * This is only used for documents rendered from {@link #siteDirectory} but not for those rendered from {@link AbstractSiteRenderingMojo#generatedSiteDirectory}.
+ * as the latter ones are always considered non-editable.
+ *
+ * The first directory containing a document with the given relative path is used for generating the URL (the same relative path as the document has to {@link #siteDirectory}).
+ * @since 3.22.0
+ */
+ @Parameter
+ protected File[] alternativeSiteSourceDirectories;
+
/**
* The current Maven session.
*/
@@ -320,13 +329,20 @@ public abstract class AbstractSiteRenderingMojo extends AbstractSiteDescriptorMo
// Generate static site
context.setRootDirectory(project.getBasedir());
+ final SiteDirectory mainSiteDirectory;
if (!locale.equals(SiteTool.DEFAULT_LOCALE)) {
- context.addSiteDirectory(new SiteDirectory(new File(siteDirectory, locale.toString()), true));
+ mainSiteDirectory = new SiteDirectory(new File(this.siteDirectory, locale.toString()), true);
context.addSiteDirectory(new SiteDirectory(new File(generatedSiteDirectory, locale.toString()), false));
} else {
- context.addSiteDirectory(new SiteDirectory(siteDirectory, true));
+ mainSiteDirectory = new SiteDirectory(siteDirectory, true);
context.addSiteDirectory(new SiteDirectory(generatedSiteDirectory, false));
}
+ if (alternativeSiteSourceDirectories != null) {
+ for (File additionalSiteSourceDirectory : alternativeSiteSourceDirectories) {
+ mainSiteDirectory.addAlternativeEditableSourceDirectory(additionalSiteSourceDirectory);
+ }
+ }
+ context.addSiteDirectory(mainSiteDirectory);
if (moduleExcludes != null) {
context.setModuleExcludes(moduleExcludes);
diff --git a/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java b/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java
index 5353e770..d318ad84 100644
--- a/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java
+++ b/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java
@@ -128,13 +128,7 @@ public class ReportDocumentRenderer implements DocumentRenderer {
document = document.substring(0, document.lastIndexOf('.'));
DocumentRenderingContext subSinkContext = new DocumentRenderingContext(
- docRenderingContext.getBasedir(),
- docRenderingContext.getBasedirRelativePath(),
- document,
- docRenderingContext.getParserId(),
- docRenderingContext.getExtension(),
- docRenderingContext.isEditable(),
- docRenderingContext.getGenerator());
+ docRenderingContext.getBasedir(), document, docRenderingContext.getGenerator());
// Create a sink for this subpage, based on this new document rendering context
MultiPageSubSink sink = new MultiPageSubSink(outputDirectory, outputName, subSinkContext);
diff --git a/src/site/markdown/examples/creating-content.md.vm b/src/site/markdown/examples/creating-content.md.vm
index 9b44b724..810cc6c5 100644
--- a/src/site/markdown/examples/creating-content.md.vm
+++ b/src/site/markdown/examples/creating-content.md.vm
@@ -114,6 +114,8 @@ Some properties are defined by default: see [Doxia Site Renderer's Velocity
Since version 3\.5, you can save processed markup by setting `saveProcessedContent` to `true`: see [corresponding documentation](../site-mojo.html#saveProcessedContent) for more details.
+For simple property replacement consider using [Maven Filtering](./filtering-content.html) instead of Velocity templating (also to avoid the common issues described below).
+
#[[###]]# Common Issues and Workarounds
- **dotted properties**:
diff --git a/src/site/markdown/examples/filtering-content.md b/src/site/markdown/examples/filtering-content.md
new file mode 100644
index 00000000..cc8e2a2b
--- /dev/null
+++ b/src/site/markdown/examples/filtering-content.md
@@ -0,0 +1,98 @@
+<!-- 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.-->
+
+# Overview
+
+Although sophisticated logic inside content can be implemented with [Apache Velocity Templates](creating-content.html#templating) this has the drawback that
+
+- not everyone is familiar with the Apache Velocity syntax
+- web-based UI/preview (e.g. in GitHub) does not work
+- there is conflicts between Velocity and Markdown syntax which both use `##` for different purposes and
+- Velocity overhead is way too big for performing simple property interpolation
+
+Therefore for simple property interpolation regular [Maven filtering](https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html) is often more suitable.
+
+# Setup
+
+## Filter prior site creation
+
+In order to perform Maven filtering create a dedicated source directory which is processed by [`maven-resources-plugin:copy-resources`](https://maven.apache.org/plugins/maven-resources-plugin/copy-resources-mojo.html).
+That should be executed prior to the site creation.
+In the following example the directory `src/site` is copied with filtering to `/target/site-src`:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <!-- prepare site content by filtering ${project.*} values -->
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>filter-site</id>
+ <phase>pre-site</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+ <configuration>
+ <outputDirectory>${project.build.directory}/site-src</outputDirectory>
+ <resources>
+ <resource>
+ <directory>src/site</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+ ...
+ </build>
+ ...
+</project>
+```
+
+## Adjust site source
+
+In order to generate the site from the filtered sources (after interpolation has been applied) adjust the [site source directory](../site-mojo.html#siteDirectory). In addition you should adjust the [site source being used for the edit buttons](../site-mojo.html#alternativeSiteSourceDirectories).
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <configuration>
+ ...
+ <siteDirectory>${project.build.directory}/site-src</siteDirectory>
+ <alternativeSiteSourceDirectories>${basedir}/src/site</alternativeSiteSourceDirectories>
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ ...
+ </build>
+ ...
+</project>
+```
diff --git a/src/site/site.xml b/src/site/site.xml
index 330130d3..72b4a1b3 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -37,6 +37,7 @@ under the License.
<menu name="Examples">
<item name="Creating Content" href="/examples/creating-content.html"/>
+ <item name="Filtering Content" href="/examples/filtering-content.html"/>
<item name="Configuring the Site Descriptor" href="/examples/sitedescriptor.html"/>
<item name="Building a multi-module site" href="/examples/multimodule.html"/>
<item name="Configuring Site Run" href="/examples/siterun.html"/>