This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/site-descriptor-2 in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
commit e3f36dff3ce5a836c9147236f3a97d0c7bc0ef92 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 #1546 --- 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..133813b --- /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`][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}