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

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

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>

👉 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

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

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

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

👉 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

🚀 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://[e-mail]/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:[e-mail]:your-username/your-repo.git</url>
                <branch>gh-pages</branch>
            </configuration>
        </plugin>
    </plugins>
</build>

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