Site

This is a reference for the site descriptor used in Doxia Sitetools, also known as site.xml: it is used to configure a site template (aka skin).

An XSD is available at:

https://maven.apache.org/xsd/site-2.1.0.xsd


<site xmlns="http://maven.apache.org/SITE/2.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SITE/2.1.0 https://maven.apache.org/xsd/site-2.1.0.xsd"
  name=.. combine.self=.. requireParent=.. >
  <bannerLeft name=.. href=.. target=.. >
    <image src=.. position=.. alt=.. width=.. height=.. style=.. />
  </bannerLeft>
  <bannerRight name=.. href=.. target=.. >
    <image src=.. position=.. alt=.. width=.. height=.. style=.. />
  </bannerRight>

  <publishDate position=.. format=.. timezone=.. value=.. prefix=.. fallbackValue=.. fallbackPrefix=.. />
  <version position=.. />
  <edit/>
  <poweredBy>
    <logo name=.. href=.. target=.. >
      <image src=.. position=.. alt=.. width=.. height=.. style=.. />
    </logo>
  </poweredBy>
  <mermaid useTiny=.. >
    <externalJsUrl integrity=.. referrerpolicy=.. otherAttributes=.. />
    <config/>
  </mermaid>

  <skin>
    <groupId/>
    <artifactId/>
    <version/>
  </skin>

  <body>
    <head/>
    <links>
      <item name=.. href=.. target=.. >
        <image src=.. position=.. alt=.. width=.. height=.. style=.. />
      </item>
    </links>
    <breadcrumbs>
      <item name=.. href=.. target=.. >
        <image src=.. position=.. alt=.. width=.. height=.. style=.. />
      </item>
    </breadcrumbs>

    <menu name=.. inherit=.. inheritAsRef=.. ref=.. >
      <image src=.. position=.. alt=.. width=.. height=.. style=.. />
      <item collapse=.. ref=.. name=.. href=.. target=.. >
        <item>...recursion...<item>
        <image src=.. position=.. alt=.. width=.. height=.. style=.. />
      </item>
    </menu>
    <footer/>
  </body>

  <custom/>
</site>

site

The <site> element is the root of the site decoration descriptor.

Attribute	Type	Since	Description
`name`	`String`		The full name of the project site.
`combine.self`	`String`	1.6.0	Whether to inherit configuration from a parent project site descriptor (`merge`) or not (`override`). Default value: `merge`
`requireParent`	`boolean`	2.0.0	Whether this "site.xml" should inherit from a parent "site.xml". If set to "true" it fails the build in case a parent site descriptor cannot be retrieved. It does not necessarily need to be the direct parent but just a site descriptor anywhere in the parent hierarchy. Default value: `false`

Element	Type	Since	Description
`bannerLeft`	`Banner`		Banner logo on the masthead of the site to the left.
`bannerRight`	`Banner`		Banner logo on the masthead of the site to the right.
`publishDate`	`PublishDate`		Modify the date published display properties.
`version`	`Version`		Modify the version published display properties.
`edit`	`String`	1.8.0	The base url to edit Doxia document sources. In general, `${project.scm.url}` value should do the job.
`poweredBy/logo*`	`List<Logo>`		(Many) Powered by logos list.
`mermaid`	`MermaidConfiguration`	2.1.0	The configuration used for rendering Mermaid diagrams (https://mermaid.ai/open-source/) on client-side. If the element does not exist, no Mermaid specific scripts will be included in the generated site. If it exists but the "config" field is not set, a default configuration will be used.
`skin`	`Skin`		The artifact containing the skin for the site.
`body`	`Body`		The main site content.
`custom`	`DOM`		Custom configuration for use with customized Velocity templates. Data from this field are accessible in Velocity template from `$site.custom` variable as DOM content. Example: `$site.custom.getChild( 'customElement' ).getValue()`

bannerLeft

Banner logo on the masthead of the site.

Attribute	Type	Since	Description
`name`	`String`		The name to display for the link.
`href`	`String`		The href to use for the link.
`target`	`String`	1.0.1	Where the new document will be displayed when the user follows a link, i.e. _blank opens the new document in a new window.

Element	Type	Since	Description
`image`	`Image`	2.0.0	The image for the link.

image

An image. Generates an "img" element (https://html.spec.whatwg.org/#the-img-element).

Attribute	Type	Since	Description
`src`	`String`	2.0.0	The source location. Ends up in the "img src" attribute (https://html.spec.whatwg.org/#attr-img-src).
`position`	`String`	2.0.0	Where to place the image relative to the displayed name (left or right). Default value: `left`
`alt`	`String`	2.0.0	The alternative text to use. Ends up in the "img alt" attribute (https://html.spec.whatwg.org/#alt).(
`width`	`String`	2.0.0	The width to use. Added to the generated "img style" attribute (https://html.spec.whatwg.org/#the-style-attribute) prefixed by "width: ".
`height`	`String`	2.0.0	The height to use. Added to the generated "img style" attribute (https://html.spec.whatwg.org/#the-style-attribute) prefixed by "height: ".
`style`	`String`	2.0.0	The style to use. Ends up in the "img style" attribute (https://html.spec.whatwg.org/#the-style-attribute) as is.

bannerRight

Banner logo on the masthead of the site.

Attribute	Type	Since	Description
`name`	`String`		The name to display for the link.
`href`	`String`		The href to use for the link.
`target`	`String`	1.0.1	Where the new document will be displayed when the user follows a link, i.e. _blank opens the new document in a new window.

Element	Type	Since	Description
`image`	`Image`	2.0.0	The image for the link.

publishDate

Modify display properties for the date in the header/footer. By default is the publish date.

Attribute	Type	Since	Description
`position`	`String`		Where to place the date published ("left", "right", "navigation-top", "navigation-bottom", "bottom" or "none" to hide it). Default value: `left`
`format`	`String`		Date format to use. Default value: `yyyy-MM-dd`
`timezone`	`String`	1.8.1	The timezone to use. Use `system` for the default locale for this instance of the Java Virtual Machine. Refer to `java.util.TimeZone` for details. Default value: `Etc/UTC`
`value`	`String`	2.1.0	The Velocity context key to use as source for the date. Usually one of "publishDate" or "scmLastModified". Must have a value of type `java.util.Date`. Default value: `publishDate`
`prefix`	`String`	2.1.0	The prefix to emit in front of the date. When starting with `template.` it is assumed to reference a key from the `site-renderer.properties`, otherwise it is a literal value. Default value: `template.lastpublished`
`fallbackValue`	`String`	2.1.0	The Velocity context key to use as source for the date. Used as fallback when the context given in "value" is not available. Must have a value of type `java.util.Date`. This is useful when the context given in "value" is only available for Doxia source documents (but not for reports). Default value: `date`
`fallbackPrefix`	`String`	2.1.0	The prefix to emit in front of the fallback date. When starting with `template.` it is assumed to reference a key from the `site-renderer.properties`, otherwise it is a literal value. Default value: `template.lastpublished`

version

Modify display properties for version published.

Attribute	Type	Since	Description
`position`	`String`		Where to place the version published ("left", "right", "navigation-top", "navigation-bottom", "bottom" or "none" to hide it). Default value: `left`

logo

Power by logo on the navigation.

Attribute	Type	Since	Description
`name`	`String`		The name to display for the link.
`href`	`String`		The href to use for the link.
`target`	`String`	1.0.1	Where the new document will be displayed when the user follows a link, i.e. _blank opens the new document in a new window.

Element	Type	Since	Description
`image`	`Image`	2.0.0	The image for the link.

mermaid

The configuration used for rendering Mermaid diagrams (https://mermaid.ai/open-source/) on client-side.

Attribute	Type	Since	Description
`useTiny`	`boolean`	2.1.0	If Tiny Mermaid (https://github.com/mermaid-js/mermaid/tree/develop/packages/tiny#tiny-mermaid) should be used. Only considered if "externalJsUrl" is not set. Default value: `false`

Element	Type	Since	Description
`externalJsUrl`	`ExternalJs`	2.1.0	The URL from which to request the javascript used for rendering the diagrams. If not set an embedded version of Mermaid is used (which is automatically deployed to the site).
`config`	`String`	2.1.0	The Mermaid configuration in JSON format as described in https://mermaid.ai/open-source/config/setup/mermaid/interfaces/MermaidConfig.html.

externalJsUrl

The configuration of an external JS file to be embedded in the HTML. Leads to an inclusion via the "script" element.

Element Content: The URL to include via "script" element with its "src" attribute in the HTML.

Attribute	Type	Since	Description
`integrity`	`String`	2.1.0	The integrity hash to use for the external JS file emitted in the "script" element's "integrity" attribute. Its semantics are described in https://www.w3.org/TR/sri-2/ and its usage is strongly recommended. Some example tools for calculating the value are outlined in https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity#tools_for_generating_sri_hashes.
`referrerpolicy`	`String`	2.1.0	The referrerpolicy attribute to use when requesting the external JS file. Its semantics are described in https://www.w3.org/TR/referrer-policy/ and setting it to "no-referrer" prevents sharing unnecessary information with 3rd parties. Default value: `no-referrer`
`otherAttributes`	`String`	2.1.0	Other attributes to include in the "script" element for this external JS file, in the form of a whitespace separated list of key=value pairs. The keys and values will be included as-is in the generated "script" element, without any validation.

skin

A skin artifact declaration.

Element	Type	Description
`groupId`	`String`	The skin group ID.
`artifactId`	`String`	The skin artifact ID.
`version`	`String`	The skin version.

body

The main content.

Element	Type	Since	Description
`head`	`String`	1.7.0	Additional content (like JavaScript) to include in the HEAD block of the generated pages.
`links/item*`	`List<LinkItem>`		(Many) A list of links to display in the navigation.
`breadcrumbs/item*`	`List<LinkItem>`		(Many) A list of breadcrumbs to display in the navigation.
`menu*`	`List<Menu>`		(Many) A list of menus to include in the navigation.
`footer`	`String`	1.7.0	If present, the contained text will be used instead of the generated copyright text.

item

A link in the navigation.

Attribute	Type	Since	Description
`name`	`String`		The name to display for the link.
`href`	`String`		The href to use for the link.
`target`	`String`	1.0.1	Where the new document will be displayed when the user follows a link, i.e. _blank opens the new document in a new window.

Element	Type	Since	Description
`image`	`Image`	2.0.0	The image for the link.

Attribute	Type	Description
`name`	`String`	The name to display for the menu.
`inherit`	`String`	The way in which the menu is inherited. Can be one of : `top`, `bottom` or empty. If empty the menu is not inherited (i.e. won't be exposed in sub projects) which is the default behavior. Value `bottom` means it appears below sub project's defined menus, `top` means it appears above sub project's defined menus.
`inheritAsRef`	`boolean`	If this is a reference, setting to `true` means that it will be populated in the site, whereas if it is `false`, it is populated in the parent and then inherited. Default value: `false`
`ref`	`String`	Mark this menu as reference to a pre-defined menu: `reports`, `modules` or `parent`. It will be populated at runtime with corresponding pre-defined content.

Element	Type	Since	Description
`image`	`Image`	2.0.0	The image for the menu.
`item*`	`List<MenuItem>`		(Many) A list of menu item.

item

A menu item.

Attribute	Type	Since	Description
`collapse`	`boolean`		Whether to collapse children elements of an item menu (by default). Default value: `false`
`ref`	`String`		A reference to a pre-defined menu item, such as a report (specified by the report goal name). Any elements explicitly given override those from the pre-defined reference.
`name`	`String`		The name to display for the link.
`href`	`String`		The href to use for the link.
`target`	`String`	1.0.1	Where the new document will be displayed when the user follows a link, i.e. _blank opens the new document in a new window.

Element	Type	Since	Description
`item*`	`List<MenuItem>`		(Many) A list of menu item.
`image`	`Image`	2.0.0	The image for the link.