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-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 88fc394c Move the site descriptor and site URL inheritance pages from 
the Maven Site Plugin
88fc394c is described below

commit 88fc394c32829c99c27a51db52616ac8c5e2c0cd
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 4 16:23:24 2026 +0000

    Move the site descriptor and site URL inheritance pages from the Maven Site 
Plugin
    
    apache/maven-doxia-sitetools#651. The old plugin pages redirect permanently 
to the new locations; the site descriptor page keeps its headings, so their 
anchors keep working.
---
 content/filtered-resources/.htaccess               |   2 +
 .../development/guide-plugin-documentation.md.vm   |   2 +-
 content/markdown/guides/index.md.vm                |   1 +
 .../markdown/guides/mini/guide-multimodule-site.md |  41 +++
 .../markdown/guides/mini/guide-site-descriptor.md  | 324 +++++++++++++++++++++
 content/markdown/guides/mini/guide-site.md         |   6 +-
 content/markdown/skins/index.md                    |   4 +-
 content/site.xml                                   |   1 +
 8 files changed, 374 insertions(+), 7 deletions(-)

diff --git a/content/filtered-resources/.htaccess 
b/content/filtered-resources/.htaccess
index 45c50a99..b3237e1f 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -64,6 +64,8 @@ Redirect Permanent 
/plugins/maven-site-plugin/examples/creatingskins.html /skins
 Redirect Permanent /plugins/maven-site-plugin/examples/filtering-content.html 
/guides/mini/guide-site.html#Filtering_with_Maven_Resources_Plugin
 Redirect Permanent /plugins/maven-site-plugin/examples/mermaid-diagrams.html 
/doxia/mermaid-diagrams.html
 Redirect Permanent /plugins/maven-site-plugin/examples/multimodule.html 
/guides/mini/guide-multimodule-site.html
+Redirect Permanent /plugins/maven-site-plugin/examples/sitedescriptor.html 
/guides/mini/guide-site-descriptor.html
+Redirect Permanent 
/plugins/maven-site-plugin/examples/inheritance-site-distribution-management.html
 
/guides/mini/guide-multimodule-site.html#Inheritance_of_the_Site_Distribution_Management
 Redirect Permanent 
/plugins/maven-scm-publish-plugin/examples/importing-maven-site.html 
/plugins/maven-scm-publish-plugin/
 Redirect Permanent 
/plugins/maven-site-plugin/examples/site-deploy-to-sourceforge.net.html 
/guides/mini/guide-site.html#Deploying_the_Site
 Redirect Permanent /plugins/maven-site-plugin/i18n.html 
/plugins/localization.html
diff --git 
a/content/markdown/guides/development/guide-plugin-documentation.md.vm 
b/content/markdown/guides/development/guide-plugin-documentation.md.vm
index 7b9b9b19..09eea758 100644
--- a/content/markdown/guides/development/guide-plugin-documentation.md.vm
+++ b/content/markdown/guides/development/guide-plugin-documentation.md.vm
@@ -167,7 +167,7 @@ Visibility of the information is also crucial. Uniform 
navigation links greatly
 
 #[[### Site Descriptor]]#
 
-The [site descriptor](/plugins/maven-site-plugin/examples/sitedescriptor.html) 
describes the navigation links and the layout of the page. It can be found in 
`src/site/site.xml`.
+The [site descriptor](/guides/mini/guide-site-descriptor.html) describes the 
navigation links and the layout of the page. It can be found in 
`src/site/site.xml`.
 
 You must define a [skin](../../skins/) if you are using a site descriptor. No 
default skin is applied automatically.
 
diff --git a/content/markdown/guides/index.md.vm 
b/content/markdown/guides/index.md.vm
index 13547f4c..81c81454 100644
--- a/content/markdown/guides/index.md.vm
+++ b/content/markdown/guides/index.md.vm
@@ -47,6 +47,7 @@ User Centre
 #[[#### Site]]#
 
 - [Creating a Site](./mini/guide-site.html)
+- [Configuring the Site Descriptor](./mini/guide-site-descriptor.html)
 - [Building Multi-module Sites](./mini/guide-multimodule-site.html)
 - [The APT Format](/doxia/references/apt-format.html)
 - [Snippet Macro](./mini/guide-snippet-macro.html)
diff --git a/content/markdown/guides/mini/guide-multimodule-site.md 
b/content/markdown/guides/mini/guide-multimodule-site.md
index f67edb37..7937c0cb 100644
--- a/content/markdown/guides/mini/guide-multimodule-site.md
+++ b/content/markdown/guides/mini/guide-multimodule-site.md
@@ -61,6 +61,47 @@ It is possible to inherit menus as well. To do so, use the 
`inherit` attribute i
 </site>
 ```
 
+## Inheritance of the Site Distribution Management
+
+Inside your POM you can not only configure the `distributionManagement` for 
the releases and snapshots of your project, but also where to deploy your site 
when using the [`site:deploy`](/plugins/maven-site-plugin/deploy-mojo.html) 
goal. The following configuration would deploy the project's site to a local 
directory called `bar`.
+
+```xml
+<distributionManagement>
+  <site>
+      <id>local</id>
+      <url>file:///C:/foo/bar</url>
+  </site>
+</distributionManagement>
+```
+
+The content of this directory would look similar to the following after your 
deployment:
+
+```
+bar/ (root of site)
+├── css
+└── report.html
+```
+
+All files are placed directly inside the directory, and no subdirectory named 
after the `artifactId` is created. That is a small but important difference 
from the `deploy` phase of the build lifecycle, which always creates a 
subdirectory for each project. So do not use the same site URL for several 
projects, as otherwise the files of the first deployed project are overwritten 
by the files of the second deployed one and so on.
+
+To handle this, use the same parent POM for each of your projects. A child 
project inherits the site configuration from the parent, with its `artifactId` 
appended to the URL, so each child project is deployed to its own subdirectory:
+
+```
+bar/ (root of site)
+├── css
+├── project-A
+│   ├── css
+│   └── report.html
+├── project-B
+│   ├── css
+│   └── report.html
+└── report.html
+```
+
+The site content of the parent POM is located in the root of the site 
directory, while the content of each project using the parent POM ("project-A" 
and "project-B" in the example) is located inside a subdirectory.
+
+A parent that sets `child.site.url.inherit.append.path="false"` on its 
`<site>` element tells Maven not to append the `artifactId` to the URL its 
children inherit. Since version 3.23.0, the Maven Site Plugin also no longer 
treats such a parent as the top of the site when a child declares a site URL 
outside the parent's, so the child is staged and deployed on its own instead of 
relative to the parent. To override the calculated top-level site explicitly, 
set the [`topSiteURL`](/plugins/ma [...]
+
 ## Aggregate Reports
 
 Some reports can be run against the sum of all modules: these are aggregate 
reports. This is the case of maven-javadoc-plugin, maven-jxr-plugin or 
maven-checkstyle-plugin.
diff --git a/content/markdown/guides/mini/guide-site-descriptor.md 
b/content/markdown/guides/mini/guide-site-descriptor.md
new file mode 100644
index 00000000..166ba349
--- /dev/null
+++ b/content/markdown/guides/mini/guide-site-descriptor.md
@@ -0,0 +1,324 @@
+---
+title: Configuring the Site Descriptor
+author: 
+  - Vincent Siveton
+  - Maria Odea Ching
+  - Dennis Lundberg
+date: 2011-08-14
+---
+
+<!--
+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.
+-->
+
+# Configuring the Site Descriptor
+
+You can create your own site descriptor for your project when you want to 
override the navigation tree for the site. For example, aside from the 
generated reports you want to add additional content to your site. In order for 
it to be accessible in the generated site, you must configure your site 
descriptor. You create the site descriptor in a file called `site.xml` which 
should be located in your `src/site` directory.
+
+There is a [reference documentation for the site descriptor 
v2](/doxia/doxia-sitetools/doxia-site-model/site.html) available with its XML 
Schema. If you are still leveraging the old site descriptor v1 you should 
consider 
[migrating](/doxia/doxia-sitetools/doxia-site-model/convert-to-sitedescriptor-2.x.html).
+
+Have a look at the [site descriptor for Maven Site 
Plugin](https://github.com/apache/maven-site-plugin/blob/master/src/site/site.xml)
 for a real life example.
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=3} -->
+## Title
+
+The title of each generated page will be a combination of the _site title_ and 
the title of the current page. By default the Site Plugin will use the value of 
the `<name>` element from your `pom.xml` file as the site title. The complete 
title for this page is &quot;Maven Site Plugin - Configuring the Site 
Descriptor&quot;.
+
+If you want to use a different site title, but do not want to change the 
`<name>` element in your `pom.xml`, you can configure this in your `site.xml`, 
like this:
+
+```xml
+<site name="My Site Title">
+  ...
+</site>
+```
+
+## Banner
+
+You can include some logos on top of your site, using the following syntax:
+
+```xml
+<site>
+  ...
+  <bannerLeft href="https://maven.apache.org";>
+    <image alt="Project Name" 
src="https://maven.apache.org/images/apache-maven-project-2.png"; />
+  </bannerLeft>
+
+  <bannerRight>
+    <image src="https://maven.apache.org/images/maven-logo-2.gif"; />
+  </bannerRight>
+  ...
+</site>
+```
+
+Refer to the site descriptor 
[reference](/doxia/doxia-sitetools/doxia-site-model/site.html) for a complete 
tag description.
+
+## Publish Date
+
+With the out-of-the-box Velocity template, the position of the &quot;Last 
Published&quot; date is configurable. By default, the position is on the left 
but you can change it. To do this, you can add a `<publishDate>` element to 
your `site.xml` like the following:
+
+```xml
+<site>
+  ...
+  <publishDate position="right"/>
+  ...
+</site>
+```
+
+The `position` attribute can have one of these values: `left`, `right`, 
`navigation-top`, `navigation-bottom`, `bottom`.
+
+If you want hide the publish date, you can use this in your `site.xml`:
+
+```xml
+<site>
+  ...
+  <publishDate position="none"/>
+  ...
+</site>
+```
+
+The format of the &quot;Last Published&quot; date is the ISO extended date 
format that is [recommended by the W3C](http://www.w3.org/QA/Tips/iso-date). 
Because the web has an international, cross-cultural audience it is recommended 
to _not_ change the date format. There is however a `format` attribute to the 
`<publishDate>` element that can be used if you really need a different date 
format.
+
+## Version
+
+You can show the &quot;Version&quot; of your project on the site, by adding a 
`<version>` element to your `site.xml` like this:
+
+```xml
+<site>
+  ...
+  <version position="right"/>
+  ...
+</site>
+```
+
+The `position` attribute can have the same values as the `publishDate` 
attribute, see above. If the `position` attribute is omitted, the default value 
is `left`.
+
+If you want hide the version, you can use this in your `site.xml`:
+
+```xml
+<site>
+  ...
+  <version position="none"/>
+  ...
+</site>
+```
+
+## &quot;Powered by&quot; Logo
+
+You can add your own &quot;Powered by&quot; logo to your site. To do this, you 
add a `<poweredBy>` element in your `site.xml` like this:
+
+```xml
+<site>
+  ...
+  <poweredBy>
+    <logo href="https://maven.apache.org/";>
+        <image 
src="https://maven.apache.org/images/logos/maven-feather.png"alt="Maven"/>
+    </logo>
+  </poweredBy>
+  ...
+</site>
+```
+
+## Inheritance
+
+See [ Building multi-module 
sites](https://maven.apache.org/guides/mini/guide-multimodule-site.html).
+
+## Including Generated Content
+
+Files in the format-based directory structure can be linked to by their target 
HTML filename, e.g. `${basedir}/src/site/apt/foo.apt` and 
`${basedir}/src/site/fml/faq.fml` can be linked to via:
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <menu name="Overview">
+      <item name="Foo" href="foo.html" />
+      <item name="FAQ" href="faq.html" />
+    </menu>
+    ...
+  </body>
+  ...
+</site>
+```
+
+There are also several preset menus that can be used in the site descriptor to 
include generated content from your project. These are linked via the `ref` 
attribute, like so:
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <menu ref="modules" />
+    ...
+  </body>
+  ...
+</site>
+```
+
+**Note:** The old syntax using `${reports}`, `${parent}` and `${modules}` has 
been deprecated and you are encouraged to use the new syntax instead. The 
support for the old syntax will be removed in a future version of the Site 
Plugin.
+
+The currently available preset menus are:
+
+- `reports` - a menu with links to all the generated reports for your project
+- `parent` - a menu with a link to the parent project&apos;s site
+- `modules` - a menu containing the links to the sites of the submodules of 
this project
+## Inject xhtml into &lt;head&gt;
+
+You can inject some HTML code into the generated `<head>` element of each page 
by adding a head element to the body element of your project&apos;s site 
descriptor. The following example adds some javascript:
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <head>
+      <![CDATA[<script src="/js/jquery.js" type="text/javascript"></script>]]>
+    </head>
+    ...
+  </body>
+  ...
+</site>
+```
+
+Notice: since Maven Site Plugin version 3\.5, if XHTML content is used, it has 
to be escaped, for example through CDATA XML notation. Previously, XML content 
didn&apos;t need such escaping.
+
+## Links
+
+To add links below your site logo, just add a links element to the `<body>` 
element of the site descriptor. Each item in the links element will be rendered 
as a link in a bar directly below your project&apos;s logo.
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <links>
+        <item name="Apache" href="http://www.apache.org"/>
+        <item name="Maven" href="https://maven.apache.org"/>
+    </links>
+    ...
+  </body>
+  ...
+</site>
+```
+
+## Breadcrumbs
+
+If there exists a logical hierarchy within your site modules, you may want to 
generate a series of breadcrumbs to give a way to easily navigate the project 
tree.
+
+To configure breadcrumbs, add a `<breadcrumbs>` element to the `<body>` 
element in the site descriptor. Each item element will render a link, and the 
items in the `<breadcrumbs>` element will be rendered in order. The breadcrumb 
items should be listed from highest level to lowest level.
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <breadcrumbs>
+      <item name="Doxia" href="https://maven.apache.org/doxia/index.html"/>
+      <item name="Trunk" 
href="https://maven.apache.org/doxia/doxia/index.html"/>
+    </breadcrumbs>
+    ...
+  </body>
+  ...
+</site>
+```
+
+**Note** that in a multi-module build, if the parent contains a breadcrumb and 
the inheriting site descriptor doesn&apos;t, a breadcrumb with the current site 
descriptor&apos;s name will be added automatically. See the notes on [building 
a multi-module 
site](https://maven.apache.org/guides/mini/guide-multimodule-site.html) for 
more details.
+
+## Custom footer
+
+You can replace the auto-generated footer content by specifying a custom 
`<footer>` element:
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <footer><![CDATA[All rights reserved.]]></footer>
+    ...
+  </body>
+  ...
+</site>
+```
+
+Notice: since Maven Site Plugin version 3\.5, if XHTML content is used, it has 
to be escaped, for example through CDATA XML notation. Previously, XML content 
didn&apos;t need such escaping.
+
+## Custom content
+
+There is also a dummy `<custom>` element then can be used to specify some 
arbitrary content. Note that you need to write your own velocity template to 
make use of this element, it is ignored by the default Velocity template used 
by the Site Plugin.
+
+```xml
+<site>
+  ...
+  <custom>Custom content</custom>
+  ...
+</site>
+```
+
+## Skinning
+
+Skins can be created to customize the look and feel of a site in a consistent 
way. For more information on creating a skin, see [Creating a 
Skin](https://maven.apache.org/skins/#Creating_a_skin). To use a specific skin 
in your project, you use the `<skin>` element of the site descriptor. This is a 
regular artifact or dependency-like element. For example, to use the [Maven 
Fluido Skin](/skins/maven-fluido-skin/), you would include:
+
+```xml
+<site>
+  ...
+  <skin>
+    <groupId>org.apache.maven.skins</groupId>
+    <artifactId>maven-fluido-skin</artifactId>
+    <version>2.1.0</version>
+  </skin>
+  ...
+</site>
+```
+
+**Note:** The `<version>` element is optional and, like plugins, if omitted 
the latest version available will be used. It is recommended that you always 
specify a version so that your site is reproducible over time.
+
+This skin will copy the necessary resources including CSS and if necessary use 
the included alternate Velocity template to render the site.
+
+Since version 3\.20\.0 a skin is mandatory: the site descriptor no longer 
carries a built-in default skin, and the build fails with `No skin is declared 
in the site descriptor` when none is found. The skin is normally inherited from 
the parent&apos;s site descriptor, so most projects never declare one 
themselves; projects inheriting from [Apache Parent 
POM](https://maven.apache.org/pom/asf/) get [Maven Fluido 
Skin](/skins/maven-fluido-skin/) that way. If you see that failure, check that  
[...]
+
+## Custom Properties
+
+The authors of skins have the option to use custom properties that are unique 
to their skin. The users of the skin can then specify their own values for 
these properties in their `site.xml` using the `<custom>` element.
+
+One skin that uses this is the Maven Fluido Skin. There are many examples on 
[their site](/skins/maven-fluido-skin/) showing what is possible to do with 
custom properties. Here is one example:
+
+```xml
+<site>
+  ...
+  <custom>
+    <fluidoSkin>
+      <topBarEnabled>true</topBarEnabled>
+      <sideBarEnabled>false</sideBarEnabled>
+    </fluidoSkin>
+  </custom>
+  ...
+</site>
+```
+
+## Expressions
+
+The `site.xml` can contain some expressions, like `${project.name}`. Each 
expression will be evaluated when the site is rendered.
+
+Expressions can be:
+
+- ${project.*}, for instance `${project.organization.name}` referenced in ` 
<project><organization><name> `
+- ${project.properties}, for instance `${myProperty}` referenced in ` 
<project><properties><myProperty> `
+- ${environmentVariable}, for instance `${JAVA_HOME}`
+
+**Note:**There are additional restrictions on using dotted project properties 
in content pages. See [Using Properties in 
Content](https://maven.apache.org/guides/mini/guide-site.html#Using_Properties_in_Content)
 for details on injecting properties into content pages.
+
diff --git a/content/markdown/guides/mini/guide-site.md 
b/content/markdown/guides/mini/guide-site.md
index a4c644c1..1e0d6a3a 100644
--- a/content/markdown/guides/mini/guide-site.md
+++ b/content/markdown/guides/mini/guide-site.md
@@ -76,7 +76,7 @@ Note that all of the above is optional - just one index file 
is required in one
       +- xhtml-content.html
 ```
 
-This means that `src/site/apt/content.apt` is available in the site as 
`/content.html`, whichever directory it comes from. So, in your [site 
descriptor](/plugins/maven-site-plugin/examples/sitedescriptor.html) you link 
to `index.html` and `other.html`, where the sources of these two files are 
`src/site/markdown/index.md` and `src/site/xdoc/other.xml`.
+This means that `src/site/apt/content.apt` is available in the site as 
`/content.html`, whichever directory it comes from. So, in your [site 
descriptor](/guides/mini/guide-site-descriptor.html) you link to `index.html` 
and `other.html`, where the sources of these two files are 
`src/site/markdown/index.md` and `src/site/xdoc/other.xml`.
 
 The `css` and `images` directories contain the stylesheets and images of the 
skin being used.
 
@@ -188,13 +188,11 @@ The `site.xml` file is used to describe the structure of 
the site. A sample is g
 </site>
 ```
 
-<!--TODO: deserves more explanation.-->
-
 **Note:** A skin is mandatory. Projects inheriting from the [Apache Parent 
POM](/pom/asf/) or from another parent that declares one inherit it and need no 
`<skin>` element of their own.
 
 **Note:** The `<menu ref="reports"/>` element above. When building the site, 
this is replaced by a menu with links to all the reports that you have 
configured.
 
-More information about the site descriptor is available at the [dedicated page 
of Maven Site Plugin](/plugins/maven-site-plugin/examples/sitedescriptor.html).
+For all the elements of the site descriptor, see [Configuring the Site 
Descriptor](./guide-site-descriptor.html).
 
 ## Adding Extra Resources
 
diff --git a/content/markdown/skins/index.md b/content/markdown/skins/index.md
index 2c555df3..e911c8ea 100644
--- a/content/markdown/skins/index.md
+++ b/content/markdown/skins/index.md
@@ -21,7 +21,7 @@ under the License.
 
 The following table lists skins that are available for you to use in your 
Maven generated site.
 
-**Note: You always have to define a skin, if you are using a [site 
descriptor](/plugins/maven-site-plugin/examples/sitedescriptor.html). There is 
no default skin applied automatically.**
+**Note: You always have to define a skin, if you are using a [site 
descriptor](/guides/mini/guide-site-descriptor.html). There is no default skin 
applied automatically.**
 
 ## Maintained By The Maven Project
 
@@ -51,7 +51,7 @@ The following table lists skins that are available for you to 
use in your Maven
 
 ## Instructions
 
-To apply one of these skins to your project's site, you use the `skin` element 
of the [site 
descriptor](/plugins/maven-site-plugin/examples/sitedescriptor.html).
+To apply one of these skins to your project's site, you use the `skin` element 
of the [site descriptor](/guides/mini/guide-site-descriptor.html).
 This is a regular artifact or dependency-like element.
 For example, to use the Maven Fluido Skin, you would include this in your 
`site.xml` file:
 
diff --git a/content/site.xml b/content/site.xml
index b7a0b356..df9c91e1 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -95,6 +95,7 @@ under the License.
           <item name="Plugins Validation" 
href="/guides/plugins/validation/index.html"/>
 
           <item name="Creating a site" href="/guides/mini/guide-site.html" 
collapse="true">
+            <item name="Site Descriptor" 
href="/guides/mini/guide-site-descriptor.html"/>
             <item name="Markup Formats" href="/doxia/references/index.html"/>
             <item name="Multi-module Sites" 
href="/guides/mini/guide-multimodule-site.html"/>
             <item name="Snippet Macro" 
href="/guides/mini/guide-snippet-macro.html"/>

Reply via email to