site:auto-refresh

Full name:

org.apache.maven.plugins:maven-site-plugin:3.22.0:auto-refresh

Description:

Renders the site once completely and then watches for Doxia source file changes. After modifications the affected file(s) are re-rendered and the output files updated. The goal blocks until the user presses Enter.

This is intended for use during site development to provide immediate feedback on changes. It only works on a single project and does neither consider child projects nor site staging.

Attributes:

Requires a Maven project to be executed.
Executes as an aggregator goal.
Requires dependency resolution of artifacts in scope: test.
The goal is thread-safe and supports parallel builds.
Since version: 3.22.0.

Optional Parameters

Name	Type	Since	Description
`<alternativeSiteSourceDirectories>`	`File[]`	`3.22.0`	Optional list of source directories to be used instead of `org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo.siteDirectory` for rendering edit URLs. This is only used for documents rendered from `org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo.siteDirectory` but not for those rendered from `generatedSiteDirectory`. as the latter ones are always considered non-editable. The first directory containing a document with the given relative path is used for generating the URL (the same relative path as the document has to `org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo.siteDirectory`).
`<attributes>`	`Map<String,Object>`	`-`	Additional template properties for rendering the site. See Doxia Site Renderer.
`<generateProjectInfo>`	`boolean`	`2.3`	Whether to generate the summary page for project reports: project-info.html. Default: `true` User Property: `generateProjectInfo`
`<generateReports>`	`boolean`	`-`	Whether to generate reports during initial rendering. Default: `true` User Property: `generateReports`
`<generateSitemap>`	`boolean`	`2.1`	Generate a sitemap. The result will be a "sitemap.html" file at the site root. Default: `false` User Property: `generateSitemap`
`<generatedSiteDirectory>`	`File`	`-`	Directory containing generated documentation in source format (Doxia supported markup). This is used to pick up other source docs that might have been generated at build time (by reports or any other build time mean). This directory is expected to have the same structure as `siteDirectory` (ie. one directory per Doxia-source-supported markup types). This is never editable. Default: `${project.build.directory}/generated-site` Alias: `workingDirectory`
`<inputEncoding>`	`String`	`2.3`	Specifies the input encoding. Default: `${project.build.sourceEncoding}` User Property: `encoding`
`<locales>`	`String`	`2.3`	A comma separated list of locales to render. The first valid token will be the default Locale for this site. Default: `default` User Property: `locales`
`<moduleExcludes>`	`Map<String,String>`	`-`	Module type exclusion mappings ex: `fml -> */-m1.fml` (excludes fml files ending in '-m1.fml' recursively) The configuration looks like this: <moduleExcludes> <moduleType>filename1.ext,*/sample.ext</moduleType> <!-- moduleType can be one of 'apt', 'fml' or 'xdoc'. --> <!-- The value is a comma separated list of --> <!-- filenames or fileset patterns. --> <!-- Here's an example: --> <xdoc>changes.xml,navigation.xml</xdoc> </moduleExcludes>
`<outputDirectory>`	`File`	`-`	Directory where the project sites and report distributions will be generated (as html/css/...). Default: `${project.reporting.outputDirectory}` User Property: `siteOutputDirectory`
`<outputEncoding>`	`String`	`2.3`	Specifies the output encoding. Default: `${project.reporting.outputEncoding}` User Property: `outputEncoding`
`<outputTimestamp>`	`String`	`3.9.0`	Timestamp for reproducible output archive entries, either formatted as ISO 8601 `yyyy-MM-dd'T'HH:mm:ssXXX` or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH). Default: `${project.build.outputTimestamp}`
`<pollingInterval>`	`long`	`-`	Polling interval in milliseconds for watching file changes. Default: `1000` User Property: `auto-refresh.interval`
`<relativizeSiteLinks>`	`boolean`	`2.3`	Make links in the site descriptor relative to the project URL. By default, any absolute links that appear in the site descriptor, e.g. banner hrefs, breadcrumbs, menu links, etc., will be made relative to project.url. Links will not be changed if this is set to false, or if the project has no URL defined. Default: `true` User Property: `relativizeSiteLinks`
`<saveProcessedContent>`	`boolean`	`3.5`	Whether to save Velocity processed Doxia content (`*.<ext>.vm`) to `${generatedSiteDirectory}/processed`.
`<siteDirectory>`	`File`	`2.3`	Directory containing the `site.xml` file and the source for handwritten docs (one directory per Doxia-source-supported markup types): see Doxia Markup Languages References. Default: `${basedir}/src/site`
`<skip>`	`boolean`	`3.0`	Set this to 'true' to skip site generation and staging. Default: `false` User Property: `maven.site.skip`

Parameter Details

<alternativeSiteSourceDirectories>

Optional list of source directories to be used instead of org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo.siteDirectory for rendering edit URLs. This is only used for documents rendered from org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo.siteDirectory but not for those rendered from generatedSiteDirectory. as the latter ones are always considered non-editable. The first directory containing a document with the given relative path is used for generating the URL (the same relative path as the document has to org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo.siteDirectory).

Type: java.io.File[]
Since: 3.22.0
Required: No

<attributes>

Additional template properties for rendering the site. See Doxia Site Renderer.

Type: java.util.Map<java.lang.String, java.lang.Object>
Required: No

<generateProjectInfo>

Whether to generate the summary page for project reports: project-info.html.

Type: boolean
Since: 2.3
Required: No
User Property: generateProjectInfo
Default: true

<generateReports>

Whether to generate reports during initial rendering.

Type: boolean
Required: No
User Property: generateReports
Default: true

<generateSitemap>

Generate a sitemap. The result will be a "sitemap.html" file at the site root.

Type: boolean
Since: 2.1
Required: No
User Property: generateSitemap
Default: false

<generatedSiteDirectory>

Directory containing generated documentation in source format (Doxia supported markup). This is used to pick up other source docs that might have been generated at build time (by reports or any other build time mean). This directory is expected to have the same structure as siteDirectory (ie. one directory per Doxia-source-supported markup types). This is never editable.

Type: java.io.File
Required: No
Default: ${project.build.directory}/generated-site
Alias: workingDirectory

<inputEncoding>

Specifies the input encoding.

Type: java.lang.String
Since: 2.3
Required: No
User Property: encoding
Default: ${project.build.sourceEncoding}

<locales>

A comma separated list of locales to render. The first valid token will be the default Locale for this site.

Type: java.lang.String
Since: 2.3
Required: No
User Property: locales
Default: default

<moduleExcludes>

Module type exclusion mappings ex: fml -> **/*-m1.fml (excludes fml files ending in '-m1.fml' recursively)

The configuration looks like this:

  <moduleExcludes>
    <moduleType>filename1.ext,**/*sample.ext</moduleType>
    <!-- moduleType can be one of 'apt', 'fml' or 'xdoc'. -->
    <!-- The value is a comma separated list of           -->
    <!-- filenames or fileset patterns.                   -->
    <!-- Here's an example:                               -->
    <xdoc>changes.xml,navigation.xml</xdoc>
  </moduleExcludes>

Type: java.util.Map<java.lang.String, java.lang.String>
Required: No

<outputDirectory>

Directory where the project sites and report distributions will be generated (as html/css/...).

Type: java.io.File
Required: No
User Property: siteOutputDirectory
Default: ${project.reporting.outputDirectory}

<outputEncoding>

Specifies the output encoding.

Type: java.lang.String
Since: 2.3
Required: No
User Property: outputEncoding
Default: ${project.reporting.outputEncoding}

<outputTimestamp>

Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).

Type: java.lang.String
Since: 3.9.0
Required: No
Default: ${project.build.outputTimestamp}

<pollingInterval>

Polling interval in milliseconds for watching file changes.

Type: long
Required: No
User Property: auto-refresh.interval
Default: 1000

<relativizeSiteLinks>

Make links in the site descriptor relative to the project URL. By default, any absolute links that appear in the site descriptor, e.g. banner hrefs, breadcrumbs, menu links, etc., will be made relative to project.url.

Links will not be changed if this is set to false, or if the project has no URL defined.

Type: boolean
Since: 2.3
Required: No
User Property: relativizeSiteLinks
Default: true

<saveProcessedContent>

Whether to save Velocity processed Doxia content (*.<ext>.vm) to ${generatedSiteDirectory}/processed.

Type: boolean
Since: 3.5
Required: No

<siteDirectory>

Directory containing the site.xml file and the source for handwritten docs (one directory per Doxia-source-supported markup types): see Doxia Markup Languages References.

Type: java.io.File
Since: 2.3
Required: No
Default: ${basedir}/src/site

<skip>

Set this to 'true' to skip site generation and staging.

Type: boolean
Since: 3.0
Required: No
User Property: maven.site.skip
Default: false