src/site/apt/examples/creating-content.apt.vm - maven-site-plugin - Git at Google

  ------
  Creating Content
  ------
  Dennis Lundberg
  ------
  2009-03-08
  ------

  ~~ 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


 Creating Content

   Now it's time to create some content for your site. Site
   content is structured by format, as there are several formats supported.

 %{toc|section=1|fromDepth=2|toDepth=3}

 * Documentation formats

   Here's an example of a directory structure for a site:

 -------------------
 +- src/
    +- site/
       +- apt/
       |  +- index.apt
       |
       +- fml/
       |  +- general.fml
       |  +- faq.fml
       |
       +- markdown/
       |  +- markup.md
       |
       +- xdoc/
       |  +- other.xml
       |
       +- xhtml/
       |  +- xhtml-content.xhtml
       |
       +- site.xml
 --------------------

  The <<<$\{basedir\}/src/site>>> directory which contains a site
  descriptor along with various directories corresponding to the supported
  document formats. Let's take a look at examples of the various document
  formats.

   * APT:
   The APT format ("Almost Plain Text") is a wiki-like format that allows you to
   write simple, structured documents (like this one) very quickly. A full
   reference of the
   {{{/doxia/references/apt-format.html} APT Format}} is
   available.

   * FML:
   The FML format is the FAQ format. This is the same that were used in Maven 1.x.
   For more info about the
   {{{/doxia/references/fml-format.html}FML Format}}
   check the {{{/doxia/}Doxia}} site.

   * XDoc:
   The XDoc format is the same as
   {{{/maven-1.x/using/site.html} used in Maven 1.x}}.
   A reference for the
   {{{/doxia/references/xdoc-format.html} XDoc Format}}
   is available.

   * Markdown (since maven-site-plugin 3.3):
   {{{http://en.wikipedia.org/wiki/Markdown} Markdown}} is a widespread Markup language.

   []

   Other formats are available, but the above four are recognized by default by the site plugin.
   Any other document format for which a Doxia parser exists can be used as well (see the list of
   {{{/doxia/references/index.html}Doxia Markup Languages}}),
   but in this case you need to add the corresponding Doxia dependency to your site plugin configuration, as
   explained in the last paragraph.
   Note that Doxia also supports several output formats, the site plugin only creates XHTML5.

   Note that all of the above is optional - just one index file is required in
   one of the input trees. The paths under each format will be merged together
   to form the root directory of the site. After running '<<<mvn site:site>>>'
   on the example above you will end up with this in your <<<target>>> directory:

 -------------------
 +- target/
    +- site/
       +- css/
       |
       +- images/
       |
       +- index.html
       +- general.html
       +- faq.html
       +- other.html
       +- xhtml-content.html
 --------------------

   This means that <<</src/site/apt/index.apt>>> will be available in the site as
   <<</index.html>>>. So, in {{{./sitedescriptor.html} your site descriptor}} you
   might link to <<</index.html>>> and <<</other.html>>>, where the source of
   these two files would be <<</src/site/apt/index.apt>>> and
   <<</src/site/xdoc/other.xdoc>>>.

   The <<<css>>> and <<<images>>> directories contain stylesheets and images
   from the skin being used. You can read more about skins in
   {{{./sitedescriptor.html}the site descriptor documentation}}.


 * Adding Extra Resources

   You can add any arbitrary resource to your site by including them in a
   <<<resources>>> directory as shown below. Additional CSS files can be picked
   up when they are placed in the <<<css>>> directory within the <<<resources>>>
   directory.

 -------------------
 +- src/
    +- site/
       +- resources/
          +- css/
          |  +- site.css
          |
          +- images/
             +- pic1.jpg
 --------------------

   The file <<<site.css>>> will be added to the default XHTML5 output, so it can
   be used to adjust the default Maven stylesheets if desired.

   The file <<<pic1.jpg>>> will be available via a relative reference to the
   <<<images>>> directory from any page in your site.


 * Filtering

   To filter properties into any supported documentation format, add a <<<.vm>>>
   extension to the filename.

   For example, the module for the Maven website contains a
   {{{http://svn.apache.org/repos/asf/maven/site/trunk/content/xdoc/download.xml.vm}<<<content/xdoc/download.xml.vm>>>}}
   file, which uses the expression <<<$\{currentStableVersion}>>> to filter in a
   property set in the
   {{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.

   <<Note:>> {{{http://velocity.apache.org/}Apache Velocity}} is used to apply the filtering.

   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}}.

   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
   {{{https://velocity.apache.org/engine/2.3/vtl-reference.html#single-line-comments}single line comment}} in Velocity,
   Markdown headers using this syntax are suppressed from generated content.

   You can use {{{https://velocity.apache.org/engine/2.3/vtl-reference.html#unparsed-content}unparsed content syntax}}
   <<<${esc.h}[[#[[##]]#]]${esc.h}>>> or
   {{{https://velocity.apache.org/tools/3.1/apidocs/org/apache/velocity/tools/generic/EscapeTool.html}escape tool}}
   like <<<${esc.d}\{esc.h\}${esc.d}\{esc.h\}>>>.

 * Internationalization

   Internationalization in Maven is very simple, as long as the reports you are
   using have that particular locale defined. For an overview of supported
   languages and instructions on how to add further languages, please see the
   related article {{{../i18n.html} Internationalization}}.

   To enable multiple locales, or languages, add a configuration similar to the
   following to your POM:

 +------------------
 <project>
   ...
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-site-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
           <locales>default,fr</locales>
         </configuration>
       </plugin>
     </plugins>
   </build>
   ...
 </project>
 +------------------

   This will generate both a default (<<<Locale#ROOT>>>) and a French version of the site.
   It will be generated at the root of the site, with a copy of the French
   translation of the site in the <<<fr/>>> subdirectory.

   To add your own content for that translation instead of using the default,
   create a subdirectory with that locale's name in your site directory and
   create a new site descriptor with the name of the locale in the file name.
   For example:

 -------------------
 +- src/
    +- site/
       +- apt/
       |  +- index.apt     (Default version)
       |
       +- fr/
       |  +- apt/
       |     +- index.apt  (French version)
       |
       +- site.xml         (Default site descriptor)
       +- site_fr.xml      (French site descriptor)
 --------------------

   With one site descriptor per language, the translated site(s) can evolve
   independently.
	------
	Creating Content
	------
	Dennis Lundberg
	------
	2009-03-08
	------

	~~ 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


	Creating Content

	Now it's time to create some content for your site. Site
	content is structured by format, as there are several formats supported.

	%{toc\|section=1\|fromDepth=2\|toDepth=3}

	* Documentation formats

	Here's an example of a directory structure for a site:

	-------------------
	+- src/
	+- site/
	+- apt/
	\| +- index.apt
	\|
	+- fml/
	\| +- general.fml
	\| +- faq.fml
	\|
	+- markdown/
	\| +- markup.md
	\|
	+- xdoc/
	\| +- other.xml
	\|
	+- xhtml/
	\| +- xhtml-content.xhtml
	\|
	+- site.xml
	--------------------

	The <<<$\{basedir\}/src/site>>> directory which contains a site
	descriptor along with various directories corresponding to the supported
	document formats. Let's take a look at examples of the various document
	formats.

	* APT:
	The APT format ("Almost Plain Text") is a wiki-like format that allows you to
	write simple, structured documents (like this one) very quickly. A full
	reference of the
	{{{/doxia/references/apt-format.html} APT Format}} is
	available.

	* FML:
	The FML format is the FAQ format. This is the same that were used in Maven 1.x.
	For more info about the
	{{{/doxia/references/fml-format.html}FML Format}}
	check the {{{/doxia/}Doxia}} site.

	* XDoc:
	The XDoc format is the same as
	{{{/maven-1.x/using/site.html} used in Maven 1.x}}.
	A reference for the
	{{{/doxia/references/xdoc-format.html} XDoc Format}}
	is available.

	* Markdown (since maven-site-plugin 3.3):
	{{{http://en.wikipedia.org/wiki/Markdown} Markdown}} is a widespread Markup language.

	[]

	Other formats are available, but the above four are recognized by default by the site plugin.
	Any other document format for which a Doxia parser exists can be used as well (see the list of
	{{{/doxia/references/index.html}Doxia Markup Languages}}),
	but in this case you need to add the corresponding Doxia dependency to your site plugin configuration, as
	explained in the last paragraph.
	Note that Doxia also supports several output formats, the site plugin only creates XHTML5.

	Note that all of the above is optional - just one index file is required in
	one of the input trees. The paths under each format will be merged together
	to form the root directory of the site. After running '<<<mvn site:site>>>'
	on the example above you will end up with this in your <<<target>>> directory:

	-------------------
	+- target/
	+- site/
	+- css/
	\|
	+- images/
	\|
	+- index.html
	+- general.html
	+- faq.html
	+- other.html
	+- xhtml-content.html
	--------------------

	This means that <<</src/site/apt/index.apt>>> will be available in the site as
	<<</index.html>>>. So, in {{{./sitedescriptor.html} your site descriptor}} you
	might link to <<</index.html>>> and <<</other.html>>>, where the source of
	these two files would be <<</src/site/apt/index.apt>>> and
	<<</src/site/xdoc/other.xdoc>>>.

	The <<<css>>> and <<<images>>> directories contain stylesheets and images
	from the skin being used. You can read more about skins in
	{{{./sitedescriptor.html}the site descriptor documentation}}.


	* Adding Extra Resources

	You can add any arbitrary resource to your site by including them in a
	<<<resources>>> directory as shown below. Additional CSS files can be picked
	up when they are placed in the <<<css>>> directory within the <<<resources>>>
	directory.

	-------------------
	+- src/
	+- site/
	+- resources/
	+- css/
	\| +- site.css
	\|
	+- images/
	+- pic1.jpg
	--------------------

	The file <<<site.css>>> will be added to the default XHTML5 output, so it can
	be used to adjust the default Maven stylesheets if desired.

	The file <<<pic1.jpg>>> will be available via a relative reference to the
	<<<images>>> directory from any page in your site.


	* Filtering

	To filter properties into any supported documentation format, add a <<<.vm>>>
	extension to the filename.

	For example, the module for the Maven website contains a
	{{{http://svn.apache.org/repos/asf/maven/site/trunk/content/xdoc/download.xml.vm}<<<content/xdoc/download.xml.vm>>>}}
	file, which uses the expression <<<$\{currentStableVersion}>>> to filter in a
	property set in the
	{{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.

	<<Note:>> {{{http://velocity.apache.org/}Apache Velocity}} is used to apply the filtering.

	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}}.

	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
	{{{https://velocity.apache.org/engine/2.3/vtl-reference.html#single-line-comments}single line comment}} in Velocity,
	Markdown headers using this syntax are suppressed from generated content.

	You can use {{{https://velocity.apache.org/engine/2.3/vtl-reference.html#unparsed-content}unparsed content syntax}}
	<<<${esc.h}[[#[[##]]#]]${esc.h}>>> or
	{{{https://velocity.apache.org/tools/3.1/apidocs/org/apache/velocity/tools/generic/EscapeTool.html}escape tool}}
	like <<<${esc.d}\{esc.h\}${esc.d}\{esc.h\}>>>.

	* Internationalization

	Internationalization in Maven is very simple, as long as the reports you are
	using have that particular locale defined. For an overview of supported
	languages and instructions on how to add further languages, please see the
	related article {{{../i18n.html} Internationalization}}.

	To enable multiple locales, or languages, add a configuration similar to the
	following to your POM:

	+------------------
	<project>
	...
	<build>
	<plugins>
	<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-site-plugin</artifactId>
	<version>${project.version}</version>
	<configuration>
	<locales>default,fr</locales>
	</configuration>
	</plugin>
	</plugins>
	</build>
	...
	</project>
	+------------------

	This will generate both a default (<<<Locale#ROOT>>>) and a French version of the site.
	It will be generated at the root of the site, with a copy of the French
	translation of the site in the <<<fr/>>> subdirectory.

	To add your own content for that translation instead of using the default,
	create a subdirectory with that locale's name in your site directory and
	create a new site descriptor with the name of the locale in the file name.
	For example:

	-------------------
	+- src/
	+- site/
	+- apt/
	\| +- index.apt (Default version)
	\|
	+- fr/
	\| +- apt/
	\| +- index.apt (French version)
	\|
	+- site.xml (Default site descriptor)
	+- site_fr.xml (French site descriptor)
	--------------------

	With one site descriptor per language, the translated site(s) can evolve
	independently.