This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/apt-to-markdown in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
commit c11f0c0debe1b528271c46e2ffacbd2929178fc6 Author: Konrad Windszus <[email protected]> AuthorDate: Tue Mar 31 16:03:16 2026 +0200 Convert APT to markdown --- doxia-integration-tools/src/site/markdown/index.md | 99 +++---- doxia-integration-tools/src/site/markdown/usage.md | 62 ++--- doxia-site-model/src/site/markdown/index.md | 73 +++-- doxia-site-renderer/src/site/markdown/index.md.vm | 310 +++++++++------------ doxia-skin-model/src/site/markdown/index.md | 77 +++-- 5 files changed, 257 insertions(+), 364 deletions(-) diff --git a/doxia-integration-tools/src/site/markdown/index.md b/doxia-integration-tools/src/site/markdown/index.md index da87a9a..85ec8d3 100644 --- a/doxia-integration-tools/src/site/markdown/index.md +++ b/doxia-integration-tools/src/site/markdown/index.md @@ -1,73 +1,52 @@ - ------ - Introduction - ------ - Dennis Lundberg - Hervé Boutemy - ------ - 2016-03-27 - ------ +--- +title: Introduction +author: + - Dennis Lundberg + - Hervé Boutemy +date: 2016-03-27 +--- - ~~ 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. +<!-- 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.--> - ~~ NOTE: For help with the syntax of this file, see: - ~~ http://maven.apache.org/doxia/references/apt-format.html +# Maven Doxia Integration Tools +This shared component has some utilities that are useful when integrating Doxia in Maven, mainly for site generation and report creation. -Maven Doxia Integration Tools +The main entry point is the [SiteTool](./apidocs/org/apache/maven/doxia/tools/SiteTool.html) Plexus component. - This shared component has some utilities that are useful when integrating Doxia in Maven, - mainly for site generation and report creation. +## Usage - The main entry point is the - {{{./apidocs/org/apache/maven/doxia/tools/SiteTool.html}SiteTool}} Plexus component. +Instructions on how to use the integration of Doxia in Maven can be found [here](./usage.html). -* Usage +## `site.xml` Model Interpolation - Instructions on how to use the integration of Doxia in Maven can be found {{{./usage.html}here}}. +Interpolation of [`site.xml` model](../doxia-site-model/site.html) injects Maven project's information, replacing `${...}` with calculated values like it happens in [Maven model interpolation](/ref/current/maven-model-builder/#Model_Interpolation). -* <<<site.xml>>> Model Interpolation +Interpolation can be **late** or **early**: - Interpolation of {{{../doxia-site-model/site.html}<<<site.xml>>> model}} injects - Maven project's information, replacing <<<$\{...\}>>> with calculated values - like it happens in {{{/ref/current/maven-model-builder/#Model_Interpolation}Maven model interpolation}}. +- with **late** interpolation, replacement happens **after** inheritance. This is the classical behaviour in Maven pom, +- with **early** interpolation, replacement happens **before** inheritance: this was the default behaviour for `project.*` values until Doxia Sitetools 1\.7 \(used in [ Maven Site Plugin 3\.5](/plugins/maven-site-plugin/history.html)\), when these early and late interpolation definitions didn't exist. Since Doxia Sitetools 1\.7\.1 \(used in [ Maven Site Plugin 3\.5\.1](/plugins/maven-site-plugin/history.html)\), early interpolation happens for `this.*` values. Early interpolation do [...] - Interpolation can be <<late>> or <<early>>: +Values are evaluated in sequence from different syntaxes: - * with <<late>> interpolation, replacement happens <<after>> inheritance. This is the classical behaviour in Maven pom, +|late value|early value|evaluation result|common examples| +|:---|:---|:---|:---| +|`project.*`|`this.*`|POM content \(see [POM reference](/ref/current/maven-model/maven.html)\)|`${project.version}` <br />`${this.url}`| +|`*`|`this.*`|model properties, such as project properties set in the pom|`${any.key}` <br />`${this.any.key}`| +|`env.*` <br />`*`||environment variables|`${env.PATH}`| - * with <<early>> interpolation, replacement happens <<before>> inheritance: this was the default behaviour for <<<project.*>>> - values until Doxia Sitetools 1.7 (used in {{{/plugins/maven-site-plugin/history.html} Maven Site Plugin 3.5}}), when these early and late interpolation definitions didn't exist. - Since Doxia Sitetools 1.7.1 (used in {{{/plugins/maven-site-plugin/history.html} Maven Site Plugin 3.5.1}}), early interpolation happens for <<<this.*>>> values. - Early interpolation doesn't support user and system properties. - - [] - - Values are evaluated in sequence from different syntaxes: - -*-----------------+--------------+--------------------+------------------+ -|| late value || early value || evaluation result || common examples || -*-----------------+--------------+--------------------+------------------+ -| <<<project.*>>> | <<<this.*>>> | POM content (see {{{/ref/current/maven-model/maven.html}POM reference}}) | <<<$\{project.version\}>>>\ - | | | <<<$\{this.url\}>>> -*-----------------+--------------+--------------------+------------------+ -| <<<*>>> | <<<this.*>>> | model properties, such as project properties set in the pom | <<<$\{any.key\}>>>\ - | | | <<<$\{this.any.key\}>>> -*-----------------+--------------+--------------------+------------------+ -| <<<env.*>>>\ -<<<*>>> | | environment variables | <<<$\{env.PATH\}>>> -*-----------------+--------------+--------------------+------------------+ diff --git a/doxia-integration-tools/src/site/markdown/usage.md b/doxia-integration-tools/src/site/markdown/usage.md index 748b3a4..928ee8f 100644 --- a/doxia-integration-tools/src/site/markdown/usage.md +++ b/doxia-integration-tools/src/site/markdown/usage.md @@ -1,35 +1,31 @@ - ------ - Usage - ------ - Dennis Lundberg - Vincent Siveton - ------ - 2008-04-27 - ------ +--- +title: Usage +author: + - Dennis Lundberg + - Vincent Siveton +date: 2008-04-27 +--- - ~~ 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. +<!-- 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.--> - ~~ NOTE: For help with the syntax of this file, see: - ~~ http://maven.apache.org/doxia/references/apt-format.html +# Using the SiteTool in a Mojo -Using the SiteTool in a Mojo - -+----- +```unknown ... import org.apache.maven.doxia.tools.SiteTool; import org.apache.maven.plugins.annotations.Component; @@ -62,10 +58,8 @@ public class YourOwnMojo extends AbstractMojo ... } -+----- - -* References +``` - [[1]] {{{./apidocs/org/apache/maven/doxia/tools/SiteTool.html}SiteTool API}} +## References - [] \ No newline at end of file +1. [SiteTool API](./apidocs/org/apache/maven/doxia/tools/SiteTool.html) diff --git a/doxia-site-model/src/site/markdown/index.md b/doxia-site-model/src/site/markdown/index.md index 6af35a3..e80c4fd 100644 --- a/doxia-site-model/src/site/markdown/index.md +++ b/doxia-site-model/src/site/markdown/index.md @@ -1,51 +1,42 @@ - ----- - Doxia Sitetool Site Model - ----- - Hervé Boutemy - ----- - 2011-08-18 - ----- +--- +title: Doxia Sitetool Site Model +author: + - Hervé Boutemy +date: 2011-08-18 +--- - ~~ 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. +<!-- 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.--> - ~~ NOTE: For help with the syntax of this file, see: - ~~ http://maven.apache.org/doxia/references/apt-format.html +# Doxia Sitetool Site Model -Doxia Sitetool Site Model +This is strictly the model for Doxia Sitetool Site Model, used in maven-site-plugin as `site.xml` to inject parameters into site template: see [Doxia Site Renderer](../doxia-site-renderer/) for more details on site rendering. - This is strictly the model for Doxia Sitetool Site Model, used in maven-site-plugin as <<<site.xml>>> to inject - parameters into site template: see {{{../doxia-site-renderer/}Doxia Site Renderer}} for more details on site rendering. +The following are generated from this model: - The following are generated from this model: +- [Java sources](./apidocs/index.html) with Reader and Writers for the Xpp3 XML parser +- A [Descriptor Reference](./site.html) +- An XSD referenced in the [Descriptor Reference](./site.html). - * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the Xpp3 XML parser +## Inheritance - * A {{{./site.html}Descriptor Reference}} +Site model can be merged from a parent `site.xml` into a child `site.xml` using `SiteModelInheritanceAssembler` \([javadoc](./apidocs/org/apache/maven/doxia/site/inheritance/SiteModelInheritanceAssembler.html)\) with its `DefaultSiteModelInheritanceAssembler` implementation \([source](./xref/org/apache/maven/doxia/site/inheritance/DefaultSiteModelInheritanceAssembler.html)\). - * An XSD referenced in the {{{./site.html}Descriptor Reference}}. +## Interpolation -* Inheritance +Interpolation is not done here: see [ Doxia Integration Tools](../doxia-integration-tools/) documentation for more details. - Site model can be merged from a parent <<<site.xml>>> into a child <<<site.xml>>> using - <<<SiteModelInheritanceAssembler>>> ({{{./apidocs/org/apache/maven/doxia/site/inheritance/SiteModelInheritanceAssembler.html}javadoc}}) - with its <<<DefaultSiteModelInheritanceAssembler>>> implementation - ({{{./xref/org/apache/maven/doxia/site/inheritance/DefaultSiteModelInheritanceAssembler.html}source}}). - -* Interpolation - - Interpolation is not done here: see {{{../doxia-integration-tools/} Doxia Integration Tools}} documentation for more details. diff --git a/doxia-site-renderer/src/site/markdown/index.md.vm b/doxia-site-renderer/src/site/markdown/index.md.vm index 2e301ec..26d893c 100644 --- a/doxia-site-renderer/src/site/markdown/index.md.vm +++ b/doxia-site-renderer/src/site/markdown/index.md.vm @@ -1,189 +1,129 @@ - ----- - Introduction - ----- - Hervé Boutemy - Dennis Lundberg - ------ - 2015-12-20 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Doxia Sitetools - Site Renderer - - The Site Renderer handles the rendering of sites, assembling a common site template (also called <a skin>) - with a collection of documents. - - Documents can be dynamically generated with {{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}, like Maven reports, - or simply read from static files written in {{{/doxia/references/index.html}markup supported by Doxia Parsers}}, - optionally preprocessed by {{{https://velocity.apache.org/engine/${velocityEngineVersion}/}Velocity}} - if their file names end with <<<.vm>>>. - -[doxia-site-renderer.png] - -* Doxia Site Skins - - A default site template is included (see <<<default-site.vm>>>), but other templates can be used at will, - either as a standalone template or packaged in a {{{../doxia-skin-model/}<<skin>> artifact}}. - - Maven team provides {{{/skins/}a collection of skins}} for projects use. - - Some documentation is available on {{{/plugins/maven-site-plugin/examples/creatingskins.html}how to create a new skin}}. - -* Velocity processing - - Site and documents with file names ending in <<<.vm>>> are processed by Velocity. - - The Velocity context contains some variables related to rendering context that you can use: - -*---------------------------------+----------------------+-------------------------------+ -|| Variable || Type || Description || -*---------------------------------+----------------------+-------------------------------+ -| <<<alignedFileName>>> | <<<String>>> | <<Deprecated>>: use <<<alignedFilePath>>>. | -*---------------------------------+----------------------+-------------------------------+ -| <<<alignedFilePath>>> | <<<String>>> | The file path of the (HTML) document being rendered, relative to the document being rendered. | -*---------------------------------+----------------------+-------------------------------+ -| <<<decoration>>> | {{{../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html}<<<SiteModel>>>}} | <<Deprecated>>: use <<<site>>>. | -*---------------------------------+----------------------+-------------------------------+ -| <<<currentFileName>>> | <<<String>>> | <<Deprecated>>: use <<<currentFilePath>>>. | -*---------------------------------+----------------------+-------------------------------+ -| <<<currentFilePath>>> | <<<String>>> | The file path of the (HTML) document being rendered, relative to the site root. | -*---------------------------------+----------------------+-------------------------------+ -| <<<doxiaSiteRendererVersion>>> | <<<String>>> | The version of the Doxia Site Renderer in use. | -*---------------------------------+----------------------+-------------------------------+ -| <<<locale>>> | <<<Locale>>> | The locale for the document being rendered. | -*---------------------------------+----------------------+-------------------------------+ -| <<<publishDate>>> | <<<Date>>> | An optional hardcoded publish date that has been set programmatically. | -*---------------------------------+----------------------+-------------------------------+ -| <<<relativePath>>> | <<<String>>> | The path to the site root from the document being rendered. | -*---------------------------------+----------------------+-------------------------------+ -| <<<scmModifiedDate>>> | <<<Date>>> | The last modified date as retrieved through {{{https://maven.apache.org/scm/}Maven SCM}} from the underlying Doxia source. Only available if artifact {{{../doxia-site-scm-context/}<<<doxia-site-scm-context>>>}} is on the classpath. | -*---------------------------------+----------------------+-------------------------------+ -| <<<scmModifiedAuthor>>> | <<<String>>> | The author of the last commit on the file as retrieved through {{{https://maven.apache.org/scm/}Maven SCM}} from the underlying Doxia source. Only available if artifact {{{../doxia-site-scm-context/}<<<doxia-site-scm-context>>>}} is on the classpath. | -*---------------------------------+----------------------+-------------------------------+ -| <<<site>>> | {{{../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html}<<<SiteModel>>>}} | This is a model that represents the data in your {{{../doxia-site-model/site.html}<<<site.xml>>>}}. | -*---------------------------------+----------------------+-------------------------------+ -| <<<supportedLocales>>> | <<<List\<Locale\>>>> | The list of locales that the site will contain. | -*---------------------------------+----------------------+-------------------------------+ - - There are also some tools for general use: +--- +title: Introduction +author: + - Hervé Boutemy + - Dennis Lundberg +date: 2015-12-20 +--- + +<!-- 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.--> + +# Doxia Sitetools - Site Renderer + +The Site Renderer handles the rendering of sites, assembling a common site template \(also called _a skin_\) with a collection of documents. + +Documents can be dynamically generated with [Doxia Sink API](/doxia/doxia/doxia-sink-api/), like Maven reports, or simply read from static files written in [markup supported by Doxia Parsers](/doxia/references/index.html), optionally preprocessed by [Velocity](https://velocity.apache.org/engine/${velocityEngineVersion}) if their file names end with `.vm`. + + + +${esc.h}${esc.h} Doxia Site Skins + +A default site template is included \(see `default-site.vm`\), but other templates can be used at will, either as a standalone template or packaged in a [**skin** artifact](../doxia-skin-model/). + +Maven team provides [a collection of skins](/skins/) for projects use. + +Some documentation is available on [how to create a new skin](/plugins/maven-site-plugin/examples/creatingskins.html). + +${esc.h}${esc.h} Velocity processing + +Site and documents with file names ending in `.vm` are processed by Velocity. + +The Velocity context contains some variables related to rendering context that you can use: + +|Variable|Type|Description| +|:---|:---|:---| +|`alignedFileName`|`String`|**Deprecated**: use `alignedFilePath`.| +|`alignedFilePath`|`String`|The file path of the \(HTML\) document being rendered, relative to the document being rendered.| +|`decoration`|[`SiteModel`](../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html)|**Deprecated**: use `site`.| +|`currentFileName`|`String`|**Deprecated**: use `currentFilePath`.| +|`currentFilePath`|`String`|The file path of the \(HTML\) document being rendered, relative to the site root.| +|`doxiaSiteRendererVersion`|`String`|The version of the Doxia Site Renderer in use.| +|`locale`|`Locale`|The locale for the document being rendered.| +|`publishDate`|`Date`|An optional hardcoded publish date that has been set programmatically.| +|`relativePath`|`String`|The path to the site root from the document being rendered.| +|`scmModifiedDate`|`Date`|The last modified date as retrieved through [Maven SCM](https://maven.apache.org/scm/) from the underlying Doxia source. Only available if artifact [`doxia-site-scm-context`](../doxia-site-scm-context/) is on the classpath.| +|`scmModifiedAuthor`|`String`|The author of the last commit on the file as retrieved through [Maven SCM](https://maven.apache.org/scm/) from the underlying Doxia source. Only available if artifact [`doxia-site-scm-context`](../doxia-site-scm-context/) is on the classpath.| +|`site`|[`SiteModel`](../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html)|This is a model that represents the data in your [`site.xml`](../doxia-site-model/site.html).| +|`supportedLocales`|`List<Locale>`|The list of locales that the site will contain.| + +There are also some tools for general use: #set( $plexus = "https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util"; ) -*---------------------------------+------------------------------------------------------+-------------------------------+ -|| Variable || Type || Description || -*---------------------------------+------------------------------------------------------+-------------------------------+ -| <<<PathTool>>> | {{{$plexus/PathTool.html}<<<PathTool>>>}} | | -*---------------------------------+------------------------------------------------------+-------------------------------+ -| <<<StringUtils>>> | {{{$plexus/StringUtils.html}<<<StringUtils>>>}} | | -*---------------------------------+------------------------------------------------------+-------------------------------+ -| <<<plexus>>> | {{{https://github.com/eclipse/sisu.plexus/blob/master/org.eclipse.sisu.plexus/src/main/java/org/codehaus/plexus/PlexusContainer.java}<<<PlexusContainer>>>}} | | -*---------------------------------+------------------------------------------------------+-------------------------------+ - - Additionally, there are {{{https://velocity.apache.org/tools/${velocityToolsVersion}/tools-summary.html} Velocity Generic Tools}} populated - with the site locale, the site model's date format, and site renderer's resource bundle: + +|Variable|Type|Description| +|:---|:---|:---| +|`PathTool`|[`PathTool`]($plexus/PathTool.html)|| +|`StringUtils`|[`StringUtils`]($plexus/StringUtils.html)|| +|`plexus`|[`PlexusContainer`](https://github.com/eclipse/sisu.plexus/blob/master/org.eclipse.sisu.plexus/src/main/java/org/codehaus/plexus/PlexusContainer.java)|| + +Additionally, there are [Velocity Generic Tools](https://velocity.apache.org/tools/${velocityToolsVersion}/tools-summary.html) populated with the site locale, the site model's date format, and site renderer's resource bundle: #set( $generic = "https://velocity.apache.org/tools/${velocityToolsVersion}/tools-summary.html"; ) -*------------------+---------------------------------------------------------------+-------------------------------+ -|| Variable || Type || Description || -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<alternator>>> | {{{$generic${esc.hash}deprecated-tools}AlternatorTool}} | {{{$generic${esc.hash}deprecated-tools}<<Deprecated>>}}: use CSS3 nth-child(even/odd) selectors or ${esc.hash}if($foreach.index % 2). For creating alternators to easily alternate over a set of values. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<class>>> | {{{$generic${esc.hash}ClassTool}ClassTool}} | For simplifying reflective lookup of information about classes and their fields, methods and constructors. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<context>>> | {{{$generic${esc.hash}ContextTool}ContextTool}} | For convenient access to context data and metadata. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<convert>>> | {{{$generic${esc.hash}deprecated-tools}ConversionTool}} | {{{$generic${esc.hash}deprecated-tools}<<Deprecated>>}}: use NumberTool for numbers formatting/parsing, DateTool for date/time formatting/parsing, or CollectionTool for toStrings(). For converting String values to richer object Types. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<date>>> | {{{$generic${esc.hash}ComparisonDateTool}ComparisonDateTool}} | For manipulating, formatting, and comparing dates. The formatting pattern and timezone are taken from the site descriptors element "publishDate" "format and "timezone" attributes, respectively. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<display>>> | {{{$generic${esc.hash}DisplayTool}DisplayTool}} | For controlling display of references (e.g., truncating values, "pretty printing" lists, and displaying alternates when a reference is null). -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<esc>>> | {{{$generic${esc.hash}EscapeTool}EscapeTool}} | For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.). -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<field>>> | {{{$generic${esc.hash}FieldTool}FieldTool}} | For (easy) access to static fields in a class, such as string constants. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<link>>> | {{{$generic${esc.hash}LinkTool}LinkTool}} | For creating and manipulating URIs and URLs. The API for this tool is designed to closely resemble that of the VelocityView tool of the same name. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<loop>>> | {{{$generic${esc.hash}LoopTool}LoopTool}} | A convenience tool to use with <<<${esc.hash}foreach>>> loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<math>>> | {{{$generic${esc.hash}MathTool}MathTool}} | For performing math functions. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<number>>> | {{{$generic${esc.hash}NumberTool}NumberTool}} | For formatting and converting numbers. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<render>>> | {{{$generic${esc.hash}RenderTool}RenderTool}} | To evaluate and render arbitrary strings of VTL, including recursive rendering. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<text>>> | {{{$generic${esc.hash}ResourceTool}ResourceTool}} | For simplified access to resource bundles for internationalization or other dynamic content needs. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<sorter>>> | {{{$generic${esc.hash}deprecated-tools}SortTool}} | {{{$generic${esc.hash}deprecated-tools}<<Deprecated>>}}: use CollectionTool sort methods. Used to sort collections (or arrays, iterators, etc) on any arbitary set of properties exposed by the objects contained within the collection. -*------------------+---------------------------------------------------------------+-------------------------------+ -| <<<xml>>> | {{{$generic${esc.hash}XmlTool}XmlTool}} | For reading/navigating XML files. This uses dom4j under the covers and provides complete XPath support. -*------------------+---------------------------------------------------------------+-------------------------------+ - - If you intend to use custom Velocity tools, add them to the Maven Site Plugin's dependency list and make sure - that they have a bundled configuration file in <<</META-INF/maven/site-tools.xml>>>. - - See <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html${esc.hash}L483}DefaultSiteRenderer.createToolManagedVelocityContext(...)}}>>> - source for more details and the {{{https://velocity.apache.org/tools/devel/tools-summary.html}tools usage summary}}. - -** Maven Site Plugin - - When <<<doxia-site-renderer>>> is used by <<<maven-site-plugin>>>, the following template properties are defined: - -*---------------------------------+----------------------+-------------------------------+ -|| Variable || Type || Description || -*---------------------------------+----------------------+-------------------------------+ -| <<<inputEncoding>>> | <<<String>>> | | -*---------------------------------+----------------------+-------------------------------+ -| <<<outputEncoding>>> | <<<String>>> | | -*---------------------------------+----------------------+-------------------------------+ -| <<<project>>> | {{{/ref/current/maven-core/apidocs/org/apache/maven/project/MavenProject.html}<<<MavenProject>>>}} | The current project. | -*---------------------------------+----------------------+-------------------------------+ -| <project properties> | <<<String>>> | Properties defined in POM are directly available. | -*---------------------------------+----------------------+-------------------------------+ - - See <<<{{{/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.html${esc.hash}createSiteRenderingContext-java.util.Locale-}AbstractSiteRenderingMojo.createSiteRenderingContext(...)}}>>> - source for more details. - -** Site Template - - When Velocity is processing the site template (be it from skin or local template), there are a few complementary variables - available that give access to information taken from document being merged into the template: - -*---------------------------------+----------------------+-------------------------------+ -|| Variable || Type || Description || -*---------------------------------+----------------------+-------------------------------+ -| <<<authors>>> | <<<List\<String\>>>> | A list of authors from the source document. If not set is equal to <<<scmModifiedAuthor>>> (only available if artifact {{{../doxia-site-scm-context/}<<<doxia-site-scm-context>>>}} is on the classpath). | | -*---------------------------------+----------------------+-------------------------------+ -| <<<bodyContent>>> | <<<String>>> | HTML body content of the Doxia generated output. | -*---------------------------------+----------------------+-------------------------------+ -| <<<documentDate>>> | <<<String>>> | The date specified in the source document: semantics has to be chosen by document writer (document creation date, or document last modification date, or ...), and format is not enforced. If not set is equal to <<<scmModifiedDate>>> (only available if artifact {{{../doxia-site-scm-context/}<<<doxia-site-scm-context>>>}} is on the classpath). | -*---------------------------------+----------------------+-------------------------------+ -| <<<headContent>>> | <<<String>>> | HTML head content of the Doxia generated output. | -*---------------------------------+----------------------+-------------------------------+ -| <<<shortTitle>>> | <<<String>>> | The title of the document, excluding the project or site name. | -*---------------------------------+----------------------+-------------------------------+ -| <<<title>>> | <<<String>>> | The title of the document, including the project or site name. | -*---------------------------------+----------------------+-------------------------------+ -| <<<docRenderingContext>>> | {{{./apidocs/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.html}<<<DocumentRenderingContext>>>}} | (since 1.8) The document rendering context. | -*---------------------------------+----------------------+-------------------------------+ - - See <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html${esc.hash}L616}DefaultSiteRenderer.createSiteTemplateVelocityContext(...)}}>>> - source for more details. + +|Variable|Type|Description| +|:---|:---|:---| +|`alternator`|[AlternatorTool]($generic${esc.hash}deprecated-tools)|[**Deprecated**]($generic${esc.hash}deprecated-tools): use CSS3 nth-child\(even/odd\) selectors or $<a id="esc.hash"></a>esc.hashif\($foreach.index % 2\). For creating alternators to easily alternate over a set of values.| +|`class`|[ClassTool]($generic${esc.hash}ClassTool)|For simplifying reflective lookup of information about classes and their fields, methods and constructors.| +|`context`|[ContextTool]($generic${esc.hash}ContextTool)|For convenient access to context data and metadata.| +|`convert`|[ConversionTool]($generic${esc.hash}deprecated-tools)|[**Deprecated**]($generic${esc.hash}deprecated-tools): use NumberTool for numbers formatting/parsing, DateTool for date/time formatting/parsing, or CollectionTool for toStrings\(\). For converting String values to richer object Types.| +|`date`|[ComparisonDateTool]($generic${esc.hash}ComparisonDateTool)|For manipulating, formatting, and comparing dates. The formatting pattern and timezone are taken from the site descriptors element "publishDate" "format and "timezone" attributes, respectively.| +|`display`|[DisplayTool]($generic${esc.hash}DisplayTool)|For controlling display of references \(e.g., truncating values, "pretty printing" lists, and displaying alternates when a reference is null\).| +|`esc`|[EscapeTool]($generic${esc.hash}EscapeTool)|For common escaping needs in Velocity templates \(e.g. escaping html, xml, javascript etc.\).| +|`field`|[FieldTool]($generic${esc.hash}FieldTool)|For \(easy\) access to static fields in a class, such as string constants.| +|`link`|[LinkTool]($generic${esc.hash}LinkTool)|For creating and manipulating URIs and URLs. The API for this tool is designed to closely resemble that of the VelocityView tool of the same name.| +|`loop`|[LoopTool]($generic${esc.hash}LoopTool)|A convenience tool to use with `$<a id="esc.hash"></a>esc.hashforeach` loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more.| +|`math`|[MathTool]($generic${esc.hash}MathTool)|For performing math functions.| +|`number`|[NumberTool]($generic${esc.hash}NumberTool)|For formatting and converting numbers.| +|`render`|[RenderTool]($generic${esc.hash}RenderTool)|To evaluate and render arbitrary strings of VTL, including recursive rendering.| +|`text`|[ResourceTool]($generic${esc.hash}ResourceTool)|For simplified access to resource bundles for internationalization or other dynamic content needs.| +|`sorter`|[SortTool]($generic${esc.hash}deprecated-tools)|[**Deprecated**]($generic${esc.hash}deprecated-tools): use CollectionTool sort methods. Used to sort collections \(or arrays, iterators, etc\) on any arbitary set of properties exposed by the objects contained within the collection.| +|`xml`|[XmlTool]($generic${esc.hash}XmlTool)|For reading/navigating XML files. This uses dom4j under the covers and provides complete XPath support.| + +If you intend to use custom Velocity tools, add them to the Maven Site Plugin's dependency list and make sure that they have a bundled configuration file in `/META-INF/maven/site-tools.xml`. + +See [`DefaultSiteRenderer.createToolManagedVelocityContext(...)`](./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html#L483) source for more details and the [tools usage summary](https://velocity.apache.org/tools/devel/tools-summary.html). + +${esc.h}${esc.h}# Maven Site Plugin + +When `doxia-site-renderer` is used by `maven-site-plugin`, the following template properties are defined: + +|Variable|Type|Description| +|:---|:---|:---| +|`inputEncoding`|`String`|| +|`outputEncoding`|`String`|| +|`project`|[`MavenProject`](/ref/current/maven-core/apidocs/org/apache/maven/project/MavenProject.html)|The current project.| +|_project properties_|`String`|Properties defined in POM are directly available.| + +See [`AbstractSiteRenderingMojo.createSiteRenderingContext(...)`](/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.html${esc.hash}createSiteRenderingContext-java.util.Locale-) source for more details. + +${esc.h}${esc.h}# Site Template + +When Velocity is processing the site template \(be it from skin or local template\), there are a few complementary variables available that give access to information taken from document being merged into the template: + +|Variable|Type|Description| +|:---|:---|:---| +|`authors`|`List<String>`|A list of authors from the source document. If not set is equal to `scmModifiedAuthor` \(only available if artifact [`doxia-site-scm-context`](../doxia-site-scm-context/) is on the classpath\).| +|`bodyContent`|`String`|HTML body content of the Doxia generated output.| +|`documentDate`|`String`|The date specified in the source document: semantics has to be chosen by document writer \(document creation date, or document last modification date, or ...\), and format is not enforced. If not set is equal to `scmModifiedDate` \(only available if artifact [`doxia-site-scm-context`](../doxia-site-scm-context/) is on the classpath\).| +|`headContent`|`String`|HTML head content of the Doxia generated output.| +|`shortTitle`|`String`|The title of the document, excluding the project or site name.| +|`title`|`String`|The title of the document, including the project or site name.| +|`docRenderingContext`|[`DocumentRenderingContext`](./apidocs/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.html)|\(since 1\.8\) The document rendering context.| + +See [`DefaultSiteRenderer.createSiteTemplateVelocityContext(...)`](./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html${esc.hash}L616) source for more details. + diff --git a/doxia-skin-model/src/site/markdown/index.md b/doxia-skin-model/src/site/markdown/index.md index 73e9027..c7ab7a5 100644 --- a/doxia-skin-model/src/site/markdown/index.md +++ b/doxia-skin-model/src/site/markdown/index.md @@ -1,54 +1,43 @@ - ----- - Doxia Sitetools Skin Model - ----- - Hervé Boutemy - ----- - 2016-02-07 - ----- +--- +title: Doxia Sitetools Skin Model +author: + - Hervé Boutemy +date: 2016-02-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. +<!-- 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.--> - ~~ NOTE: For help with the syntax of this file, see: - ~~ http://maven.apache.org/doxia/references/apt-format.html +# Doxia Sitetools Skin Model -Doxia Sitetools Skin Model +This is strictly the model for Doxia Sitetools Skin Model, used in skins in `META-INF/maven/skin.xml`. - This is strictly the model for Doxia Sitetools Skin Model, used in skins in <<<META-INF/maven/skin.xml>>>. +The following are generated from this model: - The following are generated from this model: +- [Java sources](./apidocs/index.html) with Reader for the Xpp3 XML parser +- A [Descriptor Reference](./skin.html) +- An XSD referenced in the [Descriptor Reference](./skin.html). +## Doxia Sitetools Skin - * {{{./apidocs/index.html}Java sources}} with Reader for the Xpp3 XML parser +A Doxia Sitetools skin must contain a Velocity template named `META-INF/maven/site.vm`: it will be called by [Site Renderer](../doxia-site-renderer/index.html) with additional variables about the rendered document as documented in the [Site Template section](../doxia-site-renderer/index.html#Site_Template), the main variable being `bodyContent`. - * A {{{./skin.html}Descriptor Reference}} +Maven team provides [a collection of skins](/skins/) for projects use. - * An XSD referenced in the {{{./skin.html}Descriptor Reference}}. +Some documentation is available on [how to create a new skin](/plugins/maven-site-plugin/examples/creatingskins.html), by copying other skins to benefit from examples of breadcrumbs or menu generation from [site model](../doxia-site-model/index.html). -* Doxia Sitetools Skin +Since Doxia Sitetools 1\.7, a skin descriptor can be added in `META-INF/maven/skin.xml`. - A Doxia Sitetools skin must contain a Velocity template named <<<META-INF/maven/site.vm>>>: it will be called - by {{{../doxia-site-renderer/index.html}Site Renderer}} with additional variables about the - rendered document as documented in the {{{../doxia-site-renderer/index.html#Site_Template}Site Template section}}, - the main variable being <<<bodyContent>>>. - - Maven team provides {{{/skins/}a collection of skins}} for projects use. - - Some documentation is available on {{{/plugins/maven-site-plugin/examples/creatingskins.html}how to create a new skin}}, - by copying other skins to benefit from examples of breadcrumbs or menu generation from - {{{../doxia-site-model/index.html}site model}}. - - Since Doxia Sitetools 1.7, a skin descriptor can be added in <<<META-INF/maven/skin.xml>>>.
