This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/site-improvements in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git
commit 346e3fa09270f5d052d600232701bbe6bf14fe3f Author: Konrad Windszus <[email protected]> AuthorDate: Mon May 18 18:10:43 2026 +0200 Several site improvements Only document site descriptor v2. Move architecture from "history" to "index". Use l10n-maven-plugin in a compatible version. --- pom.xml | 4 +- src/site/markdown/examples/sitedescriptor.md | 74 ++++++++++++++-------------- src/site/markdown/history.md | 9 +--- src/site/markdown/index.md.vm | 14 +++++- 4 files changed, 51 insertions(+), 50 deletions(-) diff --git a/pom.xml b/pom.xml index a34758b5..b8a536f1 100644 --- a/pom.xml +++ b/pom.xml @@ -595,9 +595,9 @@ under the License. <reporting> <plugins> <plugin> - <groupId>com.googlecode.l10n-maven-plugin</groupId> + <groupId>org.codehaus.mojo</groupId> <artifactId>l10n-maven-plugin</artifactId> - <version>1.8</version> + <version>1.2.0</version> <configuration> <locales> <locale>ca</locale> diff --git a/src/site/markdown/examples/sitedescriptor.md b/src/site/markdown/examples/sitedescriptor.md index 1045e337..e58d0b3c 100644 --- a/src/site/markdown/examples/sitedescriptor.md +++ b/src/site/markdown/examples/sitedescriptor.md @@ -28,7 +28,7 @@ date: 2011-08-14 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](/doxia/doxia-sitetools/doxia-site-model/site.html) available with its XML Schema. +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. @@ -40,9 +40,9 @@ The title of each generated page will be a combination of the _site title_ and t 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: ```unknown -<project name="My Site Title"> +<site name="My Site Title"> ... -</project> +</site> ``` ## Banner @@ -50,19 +50,17 @@ If you want to use a different site title, but do not want to change the `<name> You can include some logos on top of your site, using the following syntax: ```unknown -<project> +<site> ... - <bannerLeft> - <name>Project Name</name> - <src>https://maven.apache.org/images/apache-maven-project-2.png</src> - <href>https://maven.apache.org/</href> + <bannerLeft href="https://maven.apache.org";> + <image alt="Project Name" src="https://maven.apache.org/images/apache-maven-project-2.png"; /> </bannerLeft> <bannerRight> - <src>https://maven.apache.org/images/maven-logo-2.gif</src> + <image src="https://maven.apache.org/images/maven-logo-2.gif"; /> </bannerRight> ... -</project> +</site> ``` Refer to the site descriptor [reference](/doxia/doxia-sitetools/doxia-site-model/site.html) for a complete tag description. @@ -72,11 +70,11 @@ Refer to the site descriptor [reference](/doxia/doxia-sitetools/doxia-site-model 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: ```unknown -<project> +<site> ... <publishDate position="right"/> ... -</project> +</site> ``` The `position` attribute can have one of these values: `left`, `right`, `navigation-top`, `navigation-bottom`, `bottom`. @@ -84,11 +82,11 @@ The `position` attribute can have one of these values: `left`, `right`, `navigat If you want hide the publish date, you can use this in your `site.xml`: ```unknown -<project> +<site> ... <publishDate position="none"/> ... -</project> +</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. @@ -98,11 +96,11 @@ The format of the "Last Published" date is the ISO extended date forma You can show the "Version" of your project on the site, by adding a `<version>` element to your `site.xml` like this: ```unknown -<project> +<site> ... <version position="right"/> ... -</project> +</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`. @@ -110,11 +108,11 @@ The `position` attribute can have the same values as the `publishDate` attribute If you want hide the version, you can use this in your `site.xml`: ```unknown -<project> +<site> ... <version position="none"/> ... -</project> +</site> ``` ## "Powered by" Logo @@ -122,14 +120,14 @@ If you want hide the version, you can use this in your `site.xml`: 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: ```unknown -<project> +<site> ... <poweredBy> <logo name="Maven" href="https://maven.apache.org/"; img="https://maven.apache.org/images/logos/maven-feather.png"/> </poweredBy> ... -</project> +</site> ``` ## Inheritance @@ -141,7 +139,7 @@ See [ Building multi-module sites](./multimodule.html). 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: ```unknown -<project> +<site> ... <body> ... @@ -152,13 +150,13 @@ Files in the format-based directory structure can be linked to by their target H ... </body> ... -</project> +</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: ```unknown -<project> +<site> ... <body> ... @@ -166,7 +164,7 @@ There are also several preset menus that can be used in the site descriptor to i ... </body> ... -</project> +</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. @@ -181,7 +179,7 @@ The currently available preset menus are: 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: ```unknown -<project> +<site> ... <body> ... @@ -191,7 +189,7 @@ You can inject some HTML code into the generated `<head>` element of each page b ... </body> ... -</project> +</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. @@ -201,7 +199,7 @@ Notice: since Maven Site Plugin version 3\.5, if XHTML content is used, it has t 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. ```unknown -<project> +<site> ... <body> ... @@ -212,7 +210,7 @@ To add links below your site logo, just add a links element to the `<body>` elem ... </body> ... -</project> +</site> ``` ## Breadcrumbs @@ -222,7 +220,7 @@ If there exists a logical hierarchy within your site modules, you may want to ge 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. ```unknown -<project> +<site> ... <body> ... @@ -233,7 +231,7 @@ To configure breadcrumbs, add a `<breadcrumbs>` element to the `<body>` element ... </body> ... -</project> +</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](./multimodule.html) for more details. @@ -243,7 +241,7 @@ To configure breadcrumbs, add a `<breadcrumbs>` element to the `<body>` element You can replace the auto-generated footer content by specifying a custom `<footer>` element: ```unknown -<project> +<site> ... <body> ... @@ -251,7 +249,7 @@ You can replace the auto-generated footer content by specifying a custom `<foote ... </body> ... -</project> +</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. @@ -261,11 +259,11 @@ Notice: since Maven Site Plugin version 3\.5, if XHTML content is used, it has t 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. ```unknown -<project> +<site> ... <custom>Custom content</custom> ... -</project> +</site> ``` ## Skinning @@ -273,7 +271,7 @@ There is also a dummy `<custom>` element then can be used to specify some arbitr 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](./creatingskins.html). 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: ```unknown -<project> +<site> ... <skin> <groupId>org.apache.maven.skins</groupId> @@ -281,7 +279,7 @@ Skins can be created to customize the look and feel of a site in a consistent wa <version>1.8</version> </skin> ... -</project> +</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. @@ -297,7 +295,7 @@ The authors of skins have the option to use custom properties that are unique to 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: ```unknown -<project> +<site> ... <custom> <fluidoSkin> @@ -306,7 +304,7 @@ One skin that uses this is the Maven Fluido Skin. There are many examples on [th </fluidoSkin> </custom> ... -</project> +</site> ``` ## Expressions diff --git a/src/site/markdown/history.md b/src/site/markdown/history.md index 967f8671..51156151 100644 --- a/src/site/markdown/history.md +++ b/src/site/markdown/history.md @@ -24,14 +24,7 @@ date: 2018-01-20 # Maven Site Plugin History -## Overview - -Maven Site Plugin uses: - -- [Doxia](/doxia/) to parse [many markup languages](/doxia/references/) then render HTML: see [Creating Content](./examples/creating-content.html) documentation for more details \(particularly which markups are enabled by default in maven-site-plugin and how to add one\), -- [Doxia Sitetools - Site Renderer](/doxia/doxia-sitetools/doxia-site-renderer/) to integrate document content into a template packaged as a skin: see [Creating Skins](./examples/creatingskins.html) documentation for more details, -- [Maven Reporting Executor](/shared/maven-reporting-exec/) to manage reports execution \(since Maven 3; reports execution was managed by Maven itself in Maven 2: see old [Using maven-site-plugin with Maven3](https://maven.apache.org/plugins-archives/maven-site-plugin-3.9.0/maven-3.html) documentation for more details\). - +The Maven site plugin leverages certain other modules outlined at [Architecture](./index.html). ## Maven Site Plugin vs Doxia vs Doxia Sitetools diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm index fbdc550c..8cb6483c 100644 --- a/src/site/markdown/index.md.vm +++ b/src/site/markdown/index.md.vm @@ -28,18 +28,28 @@ The Site Plugin is used to generate a site for the project. The generated site a Please read the [migration guide](./migrate.html) if you want to upgrade from a previous version. +#[[##]]# Architecture + +The Site Plugin uses: + +- [Doxia](/doxia/) to parse [many markup languages](/doxia/references/) then render HTML: see [Creating Content](./examples/creating-content.html) documentation for more details \(particularly which markups are enabled by default in maven-site-plugin and how to add one\), +- [Doxia Sitetools - Site Renderer](/doxia/doxia-sitetools/doxia-site-renderer/) to integrate document content into a template packaged as a skin: see [Creating Skins](./examples/creatingskins.html) documentation for more details, +- [Maven Reporting Executor](/shared/maven-reporting-exec/) to manage reports execution \(since Maven 3; reports execution was managed by Maven itself in Maven 2: see old [Using maven-site-plugin with Maven3](https://maven.apache.org/plugins-archives/maven-site-plugin-3.8.2/maven-3.html) documentation for more details\). + + #[[##]]# Goals Overview -The Site Plugin has seven goals: +The Site Plugin has the following goals: - [site:site](./site-mojo.html) is used generate a site for a single project. Note that links between module sites in a multi module build will **not** work, since local build directory structure doesn't match deployed site. - [site:deploy](./deploy-mojo.html) is used to deploy the generated site using Wagon supported protocol to the site URL specified in the `<distributionManagement>` section of the POM. -- [site:run](./run-mojo.html) starts the site up, rendering documents as requested for faster editing. It uses Jetty as the web server. +- [site:run](./run-mojo.html) starts a server, rendering documents on-demand (while requested) for faster previews. It uses Jetty as the web server. - [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: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. #[[##]]# Usage
![https://maven.apache.org/images/apache-maven-project-2.png"](https://maven.apache.org/images/apache-maven-project-2.png"){kind=link}
![https://maven.apache.org/images/maven-logo-2.gif"](https://maven.apache.org/images/maven-logo-2.gif"){kind=link}
![https://maven.apache.org/images/logos/maven-feather.png"/](https://maven.apache.org/images/logos/maven-feather.png"/){kind=link}