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:
-
pre-site→ Prepares before documentation is generated. -
site→ Generates the project documentation (HTML reports). -
post-site→ Executes tasks after the documentation is generated. -
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:
-
Collect metadata from
pom.xml(project name, version, dependencies). - Generate HTML pages (index, dependencies, reports, Javadocs).
- Aggregate reports (Surefire test reports, FindBugs, Checkstyle).
📌 How to Execute:
mvn site
🚀 This will:
- Run the
sitephase, which calls themaven-site-plugin:sitegoal. - 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:
- Connect to the deployment server (FTP, SCP, or HTTP).
-
Upload all files from
target/site/to the remote location.
📌 How to Execute:
mvn site-deploy
🚀 This will:
- Run the
site-deployphase, which calls themaven-site-plugin:deploygoal. - 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>
👉 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)