Author: hboutemy
Date: Sat Oct 21 15:49:10 2017
New Revision: 1812831
URL: http://svn.apache.org/viewvc?rev=1812831&view=rev
Log:
created "common issues and workaround" section
Modified:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt.vm
Modified:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt.vm?rev=1812831&r1=1812830&r2=1812831&view=diff
==============================================================================
---
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt.vm
(original)
+++
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt.vm
Sat Oct 21 15:49:10 2017
@@ -153,9 +153,6 @@ Creating Content
* Filtering
- <<Note:>> This feature is available in version 2.0-beta-6 or later of the
- Site Plugin.
-
To filter properties into any supported documentation format, add a <<<.vm>>>
extension to the filename.
@@ -165,23 +162,31 @@ Creating Content
property set in the
{{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.
- Since version 3.5, you can save processed markup by setting
<<<saveProcessedContent>>> to <<<true>>>: see
- {{{./site-mojo.html#saveProcessedContent}corresponding documentation}} for
more details.
-
<<Note:>> {{{http://velocity.apache.org/}Apache Velocity}} is used to apply
the filtering.
- As Velocity uses a dot-notation to traverse beans, you <<cannot>>
- use dotted properties defined in <<<\<properties\>>>> directly. It is
generally
- advised to access properties by using the <<<${esc.d}context>>> tool.
- E.g., with <<<${esc.d}context.get("my.property")>>>.
Some properties are defined by default: see
{{{/doxia/doxia-sitetools/doxia-site-renderer/#Velocity_processing} Doxia
Site Renderer's Velocity processing reference}}
for more information. For a complete usage overview, see Velocity's
{{{http://velocity.apache.org/engine/devel/user-guide.html}user guide}}.
- Another classical issue with Velocity happens when using Markdown headers:
- as <<<${esc.h}${esc.h}>>> denotes a
+ Since version 3.5, you can save processed markup by setting
<<<saveProcessedContent>>> to <<<true>>>: see
+ {{{./site-mojo.html#saveProcessedContent}corresponding documentation}} for
more details.
+
+** Common Issues and Workarounds
+
+ * <<dotted properties>>:
+
+ As Velocity uses a dot-notation to traverse beans, you <<cannot>>
+ use dotted properties defined in <<<\<properties\>>>> directly.
+
+ It is generally advised to access properties by using the
<<<${esc.d}context>>> tool:
+ e.g., with <<<${esc.d}context.get("my.property")>>>.
+
+ * <<Markdown conflict with Velocity on ${esc.h}${esc.h} syntax>>:
+
+ Since <<<${esc.h}${esc.h}>>> denotes a
{{{http://velocity.apache.org/engine/1.7/vtl-reference.html#single-line-comments}single
line comment}} in Velocity,
Markdown headers using this syntax are suppressed from generated content.
+
You can use
{{{http://velocity.apache.org/engine/1.7/vtl-reference.html#unparsed-content}unparsed
content syntax}}
<<<${esc.h}[[#[[##]]#]]${esc.h}>>> or
{{{http://velocity.apache.org/tools/2.0/apidocs/org/apache/velocity/tools/generic/EscapeTool.html}escape
tool}}
