DEV Community

Hunor Vadasz-Perhat
Hunor Vadasz-Perhat

Posted on

maven-005: deep-dive-into-site-lifecycle

#maven #programming

Deep Dive into the Maven Site Lifecycle

The Site Lifecycle in Maven is used to generate project documentation and reports. It helps developers create an HTML-based website containing project details, dependencies, test reports, and Javadocs.

1️⃣ Site Lifecycle Overview

The Site Lifecycle consists of four phases:

  1. pre-site → Prepares before documentation is generated.
  2. site → Generates the project documentation (HTML reports).
  3. post-site → Executes tasks after the documentation is generated.
  4. site-deploy → Uploads the documentation to a remote server.

Each phase can have goals (specific tasks assigned to it), which execute underlying tasks (actions performed inside each goal).

2️⃣ Site Lifecycle Structure 

Lifecycle: Site
│
├── Phase: pre-site
│   ├── (Custom goals can be added)
│
├── Phase: site
│   ├── Goal: maven-site-plugin:site
│   │   ├── Task: Collect project metadata
│   │   ├── Task: Generate HTML pages
│   │   ├── Task: Aggregate reports
│
├── Phase: post-site
│   ├── (Custom goals can be added)
│
└── Phase: site-deploy
    ├── Goal: maven-site-plugin:deploy
    ├── Task: Upload documentation to a remote site
Enter fullscreen mode Exit fullscreen mode

The main goals used in the site lifecycle are:

  • maven-site-plugin:site → Generates documentation.
  • maven-site-plugin:deploy → Deploys the generated documentation.

3️⃣ Site Lifecycle Phases, Goals, and Tasks

🔹 Phase 1: pre-site

📌 Purpose:

  • Runs before documentation generation.
  • No default goals are assigned, but developers can add custom goals.

📌 Possible Custom Goals:

  • Logging information before site generation.
  • Cleaning old documentation files.

📌 Example Custom Plugin

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-antrun-plugin</artifactId>
    <version>1.8</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>run</goal>
            </goals>
            <configuration>
                <tasks>
                    <echo>Starting site generation...</echo>
                </tasks>
            </configuration>
        </execution>
    </executions>
</plugin>
Enter fullscreen mode Exit fullscreen mode

👉 This logs "Starting site generation..." before documentation generation.

🔹 Phase 2: site

📌 Purpose:

  • Generates the project documentation.

📌 Default Goal:

  • maven-site-plugin:site

📌 Tasks Inside This Goal:

  1. Collect metadata from pom.xml (project name, version, dependencies).
  2. Generate HTML pages (index, dependencies, reports, Javadocs).
  3. Aggregate reports (Surefire test reports, FindBugs, Checkstyle).

📌 How to Execute:

mvn site
Enter fullscreen mode Exit fullscreen mode

🚀 This will:

  • Run the site phase, which calls the maven-site-plugin:site goal.
  • Generate a target/site/ directory with HTML documentation.

📌 Example Plugin Configuration in pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.9.1</version>
        </plugin>
    </plugins>
</build>
Enter fullscreen mode Exit fullscreen mode

📌 Generated Site Structure (After Running mvn site)

my-project/
├── pom.xml
├── target/
│   ├── site/
│   │   ├── index.html  (Project overview)
│   │   ├── dependencies.html  (Dependency list)
│   │   ├── test-report.html  (Test results)
│   │   ├── javadoc/  (JavaDoc API docs)
Enter fullscreen mode Exit fullscreen mode

🚀 Result: The site/ folder now contains a complete project documentation website.

🔹 Phase 3: post-site

📌 Purpose:

  • Runs after site generation.
  • No default goals, but can be customized.

📌 Possible Custom Goals:

  • Logging site generation completion.
  • Sending notifications after documentation is ready.

📌 Example: Logging Site Generation Completion

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-antrun-plugin</artifactId>
    <version>1.8</version>
    <executions>
        <execution>
            <phase>post-site</phase>
            <goals>
                <goal>run</goal>
            </goals>
            <configuration>
                <tasks>
                    <echo>Documentation generated successfully.</echo>
                </tasks>
            </configuration>
        </execution>
    </executions>
</plugin>
Enter fullscreen mode Exit fullscreen mode

👉 This logs "Documentation generated successfully." after the site phase.

🔹 Phase 4: site-deploy

📌 Purpose:

  • Uploads the generated documentation to a remote server.

📌 Default Goal:

  • maven-site-plugin:deploy

📌 Tasks Inside This Goal:

  1. Connect to the deployment server (FTP, SCP, or HTTP).
  2. Upload all files from target/site/ to the remote location.

📌 How to Execute:

mvn site-deploy
Enter fullscreen mode Exit fullscreen mode

🚀 This will:

  • Run the site-deploy phase, which calls the maven-site-plugin:deploy goal.
  • Upload the generated site.

📌 Example Plugin Configuration for Deploying to GitHub Pages

<distributionManagement>
    <site>
        <id>github</id>
        <url>scp://git@github.com/your-username/your-repo.git</url>
    </site>
</distributionManagement>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.9.1</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-scm-plugin</artifactId>
            <version>1.11.3</version>
            <configuration>
                <url>scm:git:git@github.com:your-username/your-repo.git</url>
                <branch>gh-pages</branch>
            </configuration>
        </plugin>
    </plugins>
</build>
Enter fullscreen mode Exit fullscreen mode

👉 This config allows publishing documentation to GitHub Pages.

4️⃣ Site Lifecycle Summary Table

Phase Goal Task Performed
pre-site (None by default, custom only) Runs pre-documentation tasks (e.g., backups, logging).
site maven-site-plugin:site Generates the documentation website.
post-site (None by default, custom only) Runs post-documentation tasks (e.g., logging success).
site-deploy maven-site-plugin:deploy Uploads the documentation to a remote server.

5️⃣ Key Takeaways

✅ The Site Lifecycle automates project documentation.

✅ It has four phases: pre-site, site, post-site, and site-deploy.

✅ The maven-site-plugin:site goal generates an HTML-based site.

✅ The maven-site-plugin:deploy goal uploads the generated site to a remote location.

✅ Custom goals can be added (e.g., for backups, logs, or notifications).

6️⃣ FAQ

❓ Q: Does mvn site also compile my project?

No! mvn site only generates documentation. It does not compile or package anything.

❓ Q: Where is the documentation stored?

In the target/site/ directory.

❓ Q: Can I upload the site to GitHub Pages?

Yes! Use the maven-site-plugin:deploy with GitHub Pages or any remote host.

7️⃣ Final Thoughts

The Site Lifecycle is great for generating Javadocs, dependency reports, test reports, and other documentation.🚀

Top comments (0)