------
 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. In Maven 2, the site
  content is structured by format, as there are several formats supported.

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

-------------------
+- src/
   +- site/
      +- apt/
      |  +- index.apt
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- xdoc/
      |  +- other.xml
      |
      +- site.xml
--------------------

 You notice 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.

  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
  {{{http://maven.apache.org/doxia/references/apt-format.html} APT Format}} is
  available.

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

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

  Other formats are available, but at this point these 3 are the best tested.
  There are also several possible output formats, but currently only XHTML is
  available.

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

  The <<<css>>> and <<<images>>> directories contains 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 XHTML 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

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

  For example, the module for the Maven website contains a
  {{{http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/download.apt.vm}<<<src/site/apt/download.apt.vm>>>}}
  file, which uses the expression <<<$\{currentVersion}>>> 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/}Velocity}} is used to apply the
  filtering. Because Velocity uses a dot-notation internally you can <<not>>
  use dots in your properties.

  If you declare these properties in your POM

+-----+
  <properties>
    <!-- This will not work because the name of the property has a dot in it -->
    <my.property>My value</my.property>
    <!-- This will work because the name of the property has no dot in it -->
    <myProperty>My other value</myProperty>
  </properties>
+-----+

  and then use the expression <<<$\{my.property\}>>> in your document, it will
  <<not>> work. If you instead use the expression <<<$\{myProperty\}>>> it will
  work just fine.


* 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>2.0</version>
        <configuration>
          <locales>en,fr</locales>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
-------------------

  This will generate both an English and a French version of the site. If
  <<<en>>> is your current locale, then 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.