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-doxia-sitetools.git
The following commit(s) were added to refs/heads/master by this push:
new 9eec27e Upgrade to Site Descriptor 2.x
9eec27e is described below
commit 9eec27e2ec1cceaee426473eb4d3215ee34bc5be
Author: Konrad Windszus <[email protected]>
AuthorDate: Mon Mar 30 10:46:42 2026 +0200
Upgrade to Site Descriptor 2.x
Add new menu items to sidebar for most relevant documentation pages. Add
documentation on how to upgrade to site descriptor 2.x.
This closes #626
---
doxia-integration-tools/src/site/site.xml | 7 ++-
.../site/markdown/convert-to-sitedescriptor-2.x.md | 53 ++++++++++++++++++++++
doxia-site-model/src/site/site.xml | 9 ++--
doxia-site-renderer/src/site/site.xml | 12 ++---
doxia-skin-model/src/site/site.xml | 9 ++--
src/site/site.xml | 20 +++++---
6 files changed, 85 insertions(+), 25 deletions(-)
diff --git a/doxia-integration-tools/src/site/site.xml
b/doxia-integration-tools/src/site/site.xml
index 5e8980f..74d4dcf 100644
--- a/doxia-integration-tools/src/site/site.xml
+++ b/doxia-integration-tools/src/site/site.xml
@@ -19,7 +19,10 @@ specific language governing permissions and limitations
under the License.
-->
-<project name="Doxia Integration Tools"
xmlns="http://maven.apache.org/DECORATION/1.3.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.3.0
http://maven.apache.org/xsd/decoration-1.3.0.xsd";>
+
+<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="Doxia Integration Tools">
<body>
<menu ref="parent"/>
@@ -38,4 +41,4 @@ under the License.
<menu ref="reports" />
</body>
-</project>
+</site>
diff --git
a/doxia-site-model/src/site/markdown/convert-to-sitedescriptor-2.x.md
b/doxia-site-model/src/site/markdown/convert-to-sitedescriptor-2.x.md
new file mode 100644
index 0000000..cf8b98b
--- /dev/null
+++ b/doxia-site-model/src/site/markdown/convert-to-sitedescriptor-2.x.md
@@ -0,0 +1,53 @@
+<!-- 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.-->
+
+<!-- MACRO{toc} -->
+
+# Site (Decoration) Descriptor 1.x
+
+[Site Descriptor 1.x][site-descriptor-1.x] also referred to as *Site
Decoration descriptor* was the format used with Doxia Sitetools 1.x for
`site.xml`. Its most recent version was 1.8.1 but in general it was evolved in
a backwards compatible way (i.e. elements/attributes/semantics introduced in
earlier version have not changed in later 1.x versions).
+
+# Site Descriptor 2.x
+
+With Doxia Sitetools 2.0 a new [Site Descriptor 2.0][site-descriptor-2.x] was
introduced which differs in quite some aspects from the older format and is not
backwards compatible. The main differences are:
+
+1. A new root element named `site`
+2. Use of XML attributes instead of XML element content for most elements
+3. Consolidation of image elements
+
+Not all elements/attributesfrom Site Descriptor 1.x do still exist in 2.x.
+Further details in [GH issue
263](https://github.com/apache/maven-doxia-sitetools/issues/263).
+
+Although Site Descriptor 1.x is still supported, it will lead to a deprecation
warning during build and doesn't allow to use newer features introduced with
Doxia Sitetools 2.x, therefore migration to 2.x is strongly recommended.
+
+# How to migrate
+
+One should migrate to the most recent 2.x version, which for Doxia Sitetools
2.1.0 is Site Descriptor 2.1.0.
+
+1. Convert root element from `<project ...>` to `<site ...>`
+2. Convert default namespace to `xmlns="http://maven.apache.org/SITE/2.1.0"`
+3. Optionally convert schema location to
`xsi:schemaLocation="http://maven.apache.org/SITE/2.1.0
https://maven.apache.org/xsd/site-2.1.0.xsd"`
+4. Convert XML values to attributes where appropriate. For details refer to
[Site Descriptor 1.x][site-descriptor-1.x] and [Site Descriptor
2.x][site-descriptor-2.x].
+5. Reference a [Skin compatible with descriptor
2.0](https://maven.apache.org/skins/index.html) (e.g. [`maven-fluido-skin
2.x`][maven-fluido-skin]).
+
+## Differences in Skins
+
+Some elements/attributes are interpreted differently in Skins upgraded to
Doxia Site Descriptor 2.0.0. For `maven-fluido-skin` 2.x this is `name` in
`bannerLeft` or `bannerRight`. Instead of being exposed as `img alt` text this
is now always exposed next to the image [GH issue
#216](https://github.com/apache/maven-fluido-skin/issues/216).
+
+[site-descriptor-1.x]: decoration.html
+[site-descriptor-2.x]: site.html
+[maven-fluido-skin]: https://maven.apache.org/skins/maven-fluido-skin/
diff --git a/doxia-site-model/src/site/site.xml
b/doxia-site-model/src/site/site.xml
index bd0d6ea..4e2fece 100644
--- a/doxia-site-model/src/site/site.xml
+++ b/doxia-site-model/src/site/site.xml
@@ -21,9 +21,9 @@
*/
-->
-<project name="Site Model" xmlns="http://maven.apache.org/DECORATION/1.0.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0
file:../../target/generated-site/xsd/decoration-1.0.0.xsd">
+<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">
<body>
@@ -31,7 +31,6 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
- <item name="Site Model Reference" href="site.html"/>
<item name="JavaDocs" href="apidocs/index.html"/>
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
@@ -41,4 +40,4 @@
</body>
-</project>
\ No newline at end of file
+</site>
\ No newline at end of file
diff --git a/doxia-site-renderer/src/site/site.xml
b/doxia-site-renderer/src/site/site.xml
index b3f5a67..92f941a 100644
--- a/doxia-site-renderer/src/site/site.xml
+++ b/doxia-site-renderer/src/site/site.xml
@@ -21,7 +21,10 @@
*/
-->
-<project name="Site Renderer" xmlns="http://maven.apache.org/DECORATION/1.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0
http://maven.apache.org/xsd/decoration-1.0.0.xsd";>
+
+<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 Renderer">
<body>
@@ -34,13 +37,8 @@
<!--item name="FAQ" href="faq.html"/-->
</menu>
- <menu name="Reference">
- <item name="Site Model" href="../doxia-site-model/site.html"/>
- <item name="Skin Model" href="../doxia-skin-model/skin.html"/>
- </menu>
-
<menu ref="reports"/>
</body>
-</project>
+</site>
diff --git a/doxia-skin-model/src/site/site.xml
b/doxia-skin-model/src/site/site.xml
index 82b463a..df8c180 100644
--- a/doxia-skin-model/src/site/site.xml
+++ b/doxia-skin-model/src/site/site.xml
@@ -21,9 +21,10 @@
*/
-->
-<project name="Site Model" xmlns="http://maven.apache.org/DECORATION/1.0.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0
file:../../target/generated-site/xsd/decoration-1.0.0.xsd">
+
+<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">
<body>
@@ -41,4 +42,4 @@
</body>
-</project>
+</site>
diff --git a/src/site/site.xml b/src/site/site.xml
index db67659..09c9f14 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -21,13 +21,12 @@
*/
-->
-<project name="Doxia Sitetools"
xmlns="http://maven.apache.org/DECORATION/1.7.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0
http://maven.apache.org/xsd/decoration-1.7.0.xsd";>
+<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="Doxia Sitetools">
- <bannerRight>
- <name>Doxia</name>
- <src>https://maven.apache.org/doxia/images/doxia-logo.png</src>
- <href>https://maven.apache.org/doxia/</href>
+ <bannerRight href="https://maven.apache.org/doxia/";>
+ <image src="https://maven.apache.org/doxia/images/doxia-logo.png";
alt="Doxia Logo" />
</bannerRight>
<body>
@@ -45,9 +44,16 @@
<item name="License" href="http://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
</menu>
+
+ <menu name="Documentation" inherit="bottom">
+ <item name="Site Descriptor 2.x" href="doxia-site-model/site.html "/>
+ <item name="Deprecated Site Descriptor 1.x"
href="doxia-site-model/decoration.html "/>
+ <item name="Convert to Site Descriptor 2.x"
href="doxia-site-model/convert-to-sitedescriptor-2.x.html "/>
+ <item name="Skin Descriptor" href="doxia-skin-model/skin.html "/>
+ </menu>
<menu ref="modules"/>
<menu ref="reports"/>
</body>
-</project>
+</site>
![https://maven.apache.org/doxia/images/doxia-logo.png"](https://maven.apache.org/doxia/images/doxia-logo.png"){kind=link}