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-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new e3bdd7b5 Link the site descriptor and site URL inheritance guides on
maven.apache.org
e3bdd7b5 is described below
commit e3bdd7b5c4a38dca14ad5bf357195fe94cdaf026
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 4 16:23:38 2026 +0000
Link the site descriptor and site URL inheritance guides on maven.apache.org
apache/maven-doxia-sitetools#651. The pages moved to the site guides on
maven.apache.org, which redirect the old plugin URLs.
---
src/site/markdown/examples/configuring-reports.md | 2 +-
.../inheritance-site-distribution-management.md | 65 -----
src/site/markdown/examples/sitedescriptor.md | 324 ---------------------
src/site/markdown/index.md.vm | 4 +-
src/site/markdown/usage.md | 2 +-
src/site/site.xml | 4 +-
6 files changed, 6 insertions(+), 395 deletions(-)
diff --git a/src/site/markdown/examples/configuring-reports.md
b/src/site/markdown/examples/configuring-reports.md
index 54a30f34..29fbbe43 100644
--- a/src/site/markdown/examples/configuring-reports.md
+++ b/src/site/markdown/examples/configuring-reports.md
@@ -59,7 +59,7 @@ To add these reports to your site, you must add the plugin to
the `<reporting>`
</project>
```
-If you have included the appropriate `<menu ref="reports"/>` tag in your [site
descriptor](./sitedescriptor.html), then when you regenerate the site those
items will appear in a menu called "Project Reports".
+If you have included the appropriate `<menu ref="reports"/>` tag in your [site
descriptor](https://maven.apache.org/guides/mini/guide-site-descriptor.html),
then when you regenerate the site those items will appear in a menu called
"Project Reports".
**Note:** Many report plugins provide a parameter called `outputDirectory` or
similar to specify the destination for their report outputs. This parameter is
only relevant if the report plugin is run standalone, i.e. by invocation
directly from the command line. In contrast, when reports are generated as part
of the site, the configuration of the Maven Site Plugin will determine the
effective output directory to ensure that all reports end up in a common
location.
diff --git
a/src/site/markdown/examples/inheritance-site-distribution-management.md
b/src/site/markdown/examples/inheritance-site-distribution-management.md
deleted file mode 100644
index e85ea4a1..00000000
--- a/src/site/markdown/examples/inheritance-site-distribution-management.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: Inheritance of Site Distribution Management
-author:
- - Matthias Bünger
-date: 2024-07-07
----
-
-<!--
-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.
--->
-
-# 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`](../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
-```
-
-You see that all files are placed directly inside the directory and that no
subdirectory named after the `artifactId` is created. That's a small, but
important difference in comparison how the regular `deploy` phase of the build
lifecycle works where always a subdirectory is created for each project. So you
have to be aware not to use the exact same value for the site for multiple
projects, as otherwise files of the first deployed project will be overwritten
by the files of the seco [...]
-
-To handle this easily you can use a the same parent POM with each of your
projects. When using a parent POM with a project, the site configuration is
inherited from the parent, but each child project is located in a subdirectory
with its `artifactId` name, resulting in a structure like in the following
example:
-
-```
-bar/ (root of site)
-├── css
-├── project-A
-│ ├── css
-│ └── report.html
-├── project-B
-│ ├── css
-│ └── report.html
-└── report.html
-```
-
-As you can see 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
(called "project-A" and "project-B" in the example) is
located inside a subdirectory.
-
diff --git a/src/site/markdown/examples/sitedescriptor.md
b/src/site/markdown/examples/sitedescriptor.md
deleted file mode 100644
index 166ba349..00000000
--- a/src/site/markdown/examples/sitedescriptor.md
+++ /dev/null
@@ -1,324 +0,0 @@
----
-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 "Maven Site Plugin - Configuring the Site
Descriptor".
-
-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 "Last
Published" 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 "Last Published" 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 "Version" 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>
-```
-
-## "Powered by" Logo
-
-You can add your own "Powered by" 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's site
-- `modules` - a menu containing the links to the sites of the submodules of
this project
-## Inject xhtml into <head>
-
-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'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'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'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't, a breadcrumb with the current site
descriptor'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'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'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/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 00501484..36891141 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -49,7 +49,7 @@ The Site Plugin has the following goals:
- [site:run](./run-mojo.html) starts a server, rendering documents on-demand
(while requested) for faster previews. It uses the HTTP server provided by the
JDK.
- [site:stage](./stage-mojo.html) generates a site in a local staging or mock
directory based on the site URL specified in the `<distributionManagement>`
section of the POM. It can be used to test that links between module sites in a
multi module build work. This goal requires the site to already have been
generated using the site goal, such as by calling `mvn site`.
- [site:stage-deploy](./stage-deploy-mojo.html) deploys the generated site to
a staging or mock directory to the site URL specified in the
`<distributionManagement>` section of the POM.
-- [site:attach-descriptor](./attach-descriptor-mojo.html) adds the site
descriptor (`site.xml`) to the list of files to be installed/deployed. For more
references of the site descriptor, [here's a
link](./examples/sitedescriptor.html).
+- [site:attach-descriptor](./attach-descriptor-mojo.html) adds the site
descriptor (`site.xml`) to the list of files to be installed/deployed. For more
references of the site descriptor, [here's a
link](https://maven.apache.org/guides/mini/guide-site-descriptor.html).
- [site:jar](./jar-mojo.html) bundles the site output into a JAR so that it
can be deployed to a repository.
- [site:effective-site](./effective-site-mojo.html) calculates the effective
site descriptor, after inheritance and interpolation.
- [site:auto-refresh](./auto-refresh-mojo.html) renders the site once and then
watches for changes in the source files. If a change is detected, the Doxia
source will be re-rendered.
@@ -67,7 +67,7 @@ If you feel like the plugin is missing a feature or has a
defect, you can file a
The following examples show how to use the Site Plugin in more advanced use
cases:
- [Creating
Content](https://maven.apache.org/guides/mini/guide-site.html#Creating_Content)
-- [Configuring the Site Descriptor](./examples/sitedescriptor.html)
+- [Configuring the Site
Descriptor](https://maven.apache.org/guides/mini/guide-site-descriptor.html)
- [Using Mermaid
Diagrams](https://maven.apache.org/doxia/mermaid-diagrams.html)
- [Configuring Site Run](./examples/siterun.html)
- [Excluding Document Formats](./examples/moduleexcludes.html)
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index 1fe16dc3..b5930b75 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -28,7 +28,7 @@ under the License.
# Usage
-You can put additional content (e.g. documentation, resources, etc.) in your
site. See [Creating a
site](https://maven.apache.org/guides/mini/guide-site.html) for more
information on this. If you want to change the menus, breadcrumbs, links or
logos on your pages you need to add and configure a [site
descriptor](./examples/sitedescriptor.html). If you like, you also can let
Maven generate some [reports](./examples/configuring-reports.html) for you,
based on the contents of your POM.
+You can put additional content (e.g. documentation, resources, etc.) in your
site. See [Creating a
site](https://maven.apache.org/guides/mini/guide-site.html) for more
information on this. If you want to change the menus, breadcrumbs, links or
logos on your pages you need to add and configure a [site
descriptor](https://maven.apache.org/guides/mini/guide-site-descriptor.html).
If you like, you also can let Maven generate some
[reports](./examples/configuring-reports.html) for you, based [...]
<!-- MACRO{toc|section=1|fromDepth=2|toDepth=3} -->
diff --git a/src/site/site.xml b/src/site/site.xml
index 98ee137e..cd5e739d 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -37,12 +37,12 @@ under the License.
<menu name="Examples">
<item name="Creating Content"
href="https://maven.apache.org/guides/mini/guide-site.html#Creating_Content"/>
<item name="Filtering Content"
href="https://maven.apache.org/guides/mini/guide-site.html#Filtering_with_Maven_Resources_Plugin"/>
- <item name="Configuring the Site Descriptor"
href="/examples/sitedescriptor.html"/>
+ <item name="Configuring the Site Descriptor"
href="https://maven.apache.org/guides/mini/guide-site-descriptor.html"/>
<item name="Building a multi-module site"
href="https://maven.apache.org/guides/mini/guide-multimodule-site.html"/>
<item name="Configuring Site Run" href="/examples/siterun.html"/>
<item name="Excluding Document Formats"
href="/examples/moduleexcludes.html"/>
<item name="Inheritance of the Site Distribution Management"
- href="/examples/inheritance-site-distribution-management.html"/>
+
href="https://maven.apache.org/guides/mini/guide-multimodule-site.html#Inheritance_of_the_Site_Distribution_Management"/>
<item name="Mermaid Diagrams"
href="https://maven.apache.org/doxia/mermaid-diagrams.html"/>
</menu>