---
title: Multi-module Sites
author: 
  - Vincent Siveton
  - Maria Odea Ching
  - Dennis Lundberg
  - Lukas Theussl
date: 2011-01-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.-->

# Building multi-module sites

When running `mvn site` on a top level project, Maven will build all sites for every module defined in the `modules` section of the pom individually. Note that each site is generated in each individual project&apos;s target location. As a result, relative links between different modules will NOT work. They will however work when you deploy or stage the site.

## Staging and deploying

To preview the whole tree of a multi-module site, you can use the [`site:stage`](../stage-mojo.html) goal. This will copy individual sites to their proper place at the staging location.

[`site:deploy`](../deploy-mojo.html) does the same thing as `site:stage`, but uses the url defined in the `<distributionManagement>` element of the pom as deployment location. This is usually a remote url, but both remote protocols like `scp` and local protocols like `file` are supported.

Finally, [`site:stage-deploy`](../stage-deploy-mojo.html) does the same thing as `site:deploy` but uses the `stagingDirectory` parameter as deployment location. This can be used to deploy the site to a remote staging area \(`site:stage` is always local\).

**Notes:**

- If subprojects inherit the \(distribution\) site URL from a parent POM, they will automatically append their _artifactId_ to form their effective deployment location. This goes for both the project url and the url defined in the `<distributionManagement>` element of the pom.
- If your multi-module tree does not follow the Maven conventions, or if module directories are named differently than module artifacts, you have to specify the url&apos;s for **each** child project. See also [`How does the Site Plugin use the <url> element in the POM?`](../faq.html#Use_of_url).
- The pom.xml of the topmost project in a multi-module build must define the distributionManagement URL element \(called &quot;rootURL&quot; hereafter\). The rootURL must be the topmost distributionManagement URL in the multi-module project, implying that any distributionManagement URL defined within another project in a multimodule build must start with the rootURL and append unique paths \(to be situated &quot;below&quot; the rootURL\).
- All projects in multi-module builds must define unique distributionManagement url elements, below/under the root distributionManagement URL in terms of URL path.
- If the artifactId and module name \(i.e. directory name\) are not identical for any project within a multi-module build, the distributionManagement URL element must be defined in the pom.xml file in the project.
## Inheritance

Site descriptors are inherited along the same lines as project descriptors are. If you want your project&apos;s site descriptor to be inherited, you need to attach it to the project&apos;s main artifact. You use the [`site:attach-descriptor`](../attach-descriptor-mojo.html) goal to attach the site descriptor to your project&apos;s main artifact.

In Maven 3 you must attach the site descriptor yourself, even for projects with packaging set to &quot;pom&quot;.

By default, all the parent descriptor settings are inherited with the only exception of menus, see below. From the body, the links and breadcrumbs accumulate to contain all the parent&apos;s site descriptor links and breadcrumbs. If the parent contains some breadcrumb and the inheriting site descriptor doesn&apos;t, a breadcrumb with the current site descriptor&apos;s name will be added automatically.

However, it is possible to inherit menus as well. To do so, use the `inherit` attribute in the site descriptor. This can be either `top` or `bottom`, indicating where the inherited menu will be placed. For example:

```unknown
<project>
  ...
  <body>
    ...
    <menu name="My Inherited Menu" inherit="top">
      ...
    </menu>
    ...
  </body>
  ...
</project>
```

## Aggregate Reports

Some reports can be run against the sum of every modules: these are aggregate reports. This is the case of maven-javadoc-plugin, maven-jxr-plugin or maven-checkstyle-plugin.

To benefit from aggregate reports, you must configure a reportSet in the parent pom, and turn inheritance off to avoid the aggregate report to be run in modules. For example, with maven-jxr-report:

```unknown
<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jxr-plugin</artifactId>
        <version>2.3</version>
        <reportSets>
          <reportSet>
            <id>aggregate</id>
            <inherited>false</inherited>
            <reports>
              <report>aggregate</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
  ...
</project>
```

