src/site/fml/faq.fml

<?xml version="1.0" encoding="UTF-8"?>

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

<faqs xmlns="http://maven.apache.org/FML/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/FML/1.0 http://maven.apache.org/xsd/fml-1.0.xsd" id="FAQ" title="Frequently Asked Questions">
  <part id="General">
    <faq id="What is the difference between mvn site and mvn site:site">
      <question>What is the difference between <i>mvn site</i> and <i>mvn site:site</i>?</question>
      <answer>
        <dl>
          <dt>mvn site</dt>
          <dd>
            Calls the <i>site</i> lifecycle with the associate phases (i.e. pre-site, site, post-site, site-deploy).
            See <a href="http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference">Lifecycle Reference</a>.</dd>
          <dt>mvn site:site</dt>
          <dd>Calls the <i>site</i> goal from the site plugin.
            See <a href="site-mojo.html">site:site</a>.</dd>
        </dl>
      </answer>
    </faq>
    <faq id="How do I Integrate static (X)HTML pages into my Maven site">
      <question>How do I Integrate static (X)HTML pages into my Maven site?</question>
      <answer>
        <p>
        You can integrate your static pages by following these steps:
        </p>
        <ul>
          <li>Put your static pages in the resources directory, <code>${basedir}/src/site/resources</code></li>
          <li>Create your <code>site.xml</code> and put it in <code>${basedir}/src/site</code></li>
          <li>Link to the static pages by modifying the menu section, create items and map them to the filenames of the static pages</li>
        </ul>
      </answer>
    </faq>
    <faq id="Why do my absolute links get translated into relative links">
      <question>Why do my absolute links get translated into relative links?</question>
      <answer>
        <p>
          This happens because the Site Plugin tries to make all URLs relative,
          when possible. If you have something like this defined in your
          <code>pom.xml</code>:
          <source>
<url>http://www.your.site.com/</url></source>
          and create links in your <code>site.xml</code> (just an example) like
          this:
          <source>
<links>
  <item name="Your Site" href="http://www.your.site.com/"/>
  <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
</links></source>
          You will see that the link to "Your site" will be a relative one, but
          that the link to "Maven 2" will be an absolute link.
        </p>
        <p>
          There is an
          <a href="http://jira.codehaus.org/browse/MSITE-159">issue for this in JIRA</a>,
          where you can read more about this.
        </p>
      </answer>
    </faq>
    <faq id="Why don't the links between parent and child modules work when I run &quot;mvn site&quot;?">
      <question>Why don't the links between parent and child modules work when I run "<code>mvn site</code>"?</question>
      <answer>
        <p>
          What "<code>mvn site</code>" will do for you, in a multi-project
          build, is to run "<code>mvn site</code>" for the parent and all its
          modules <b>individually</b>. The links between parent and child will
          <b>not</b> work here. They <b>will</b> however work when you deploy
          the site.
        </p>
        <p>
          If you want to test this, prior to deployment, you can run the
          <a href="stage-mojo.html"><code>site:stage</code></a> goal as
          described in the <a href="usage.html">usage documentation</a>
          instead.
        </p>
      </answer>
    </faq>
    <faq id="How to include a custom Doxia module, like Twiki">
      <question>How to include a custom Doxia module, like Twiki?</question>
      <answer>
        <p>
          The site plugin handles out-of-box apt, xdoc and fml formats. If you
          want to use a custom format like Twiki, you need to specify the
          Doxia Twiki dependency, i.e.:
          <source>
<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-twiki</artifactId>
            <version>1.0</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>
  ...
</project>
          </source>
        </p>
      </answer>
    </faq>
  </part>
</faqs>