skip to content

What is the maven-site-plugin for, and when would you still use it today?

level: juniorimportance: nice to knowfreq 15%

answer

  1. static HTML project site
  2. separate site lifecycle: site / site-deploy
  3. renders <reporting> plugins (javadoc, surefire, coverage)
  4. src/site + site.xml navigation
  5. mostly legacy / library projects now

basics

~10 s

maven-site-plugin generates a static HTML website for a project, including reports like javadoc, test results, and dependency info. It runs on the separate site lifecycle via mvn site.

solid answer

~40 s

maven-site-plugin builds project documentation as a static website. It has its own lifecycle (`pre-site`, `site`, `post-site`, `site-deploy`) separate from the default build, invoked with `mvn site`. It renders APT/Markdown/XDoc pages from `src/site` plus configured **reporting** plugins — javadoc, surefire test reports, JaCoCo coverage, dependency and plugin reports — into `target/site`, and `site:deploy` can publish it. It was central to older open-source projects' docs. Today it's largely superseded by README-driven docs, wikis, and CI report dashboards, so it's mostly seen in legacy or library projects that publish a formal project site. It's still a core plugin and useful when you want a self-contained, versioned documentation bundle generated from the POM's reporting section.

code

bash · 3 lines
bash
mvn site          # generate site into target/site
mvn site:run      # preview locally
mvn site:deploy   # publish to distributionManagement <site>

go deeper

for a junior

Know it generates a project documentation website via mvn site.

for a middle

Explain its separate lifecycle and the <reporting> section it renders.

for a senior

Judge when a generated site is worth it vs README/CI dashboards.

for a principal

Decide org documentation strategy and whether to maintain versioned generated sites for libraries.

## Purpose **maven-site-plugin** turns your project into a browsable static website: an overview, the dependency tree, plugin and license info, plus any **report** plugins you configure (javadoc, unit-test results, code coverage). It's how many Apache/library projects historically published documentation tied to a release. ## Its own lifecycle The site plugin drives a **separate lifecycle** (not the default build): - `pre-site` - `site` → goal `site:site` renders pages to `target/site` - `post-site` - `site-deploy` → goal `site:deploy` uploads the generated site (location from `<distributionManagement><site>`) You run it with `mvn site` (and `mvn site:run` to preview locally on a dev server). ## Where content comes from - Hand-written pages in `src/site` (formats: Markdown, APT, XDoc, FML), plus a `src/site/site.xml` for navigation. - The `<reporting>` section of the POM, which lists report plugins: ```xml <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> </plugin> </plugins> </reporting> ``` ## When to use it today - Library/framework projects that want a formal, versioned doc site. - Internal projects wanting an offline, self-contained report bundle (coverage + javadoc + dependency info) per build. For most modern app teams, README + a docs site (Docusaurus, etc.) + CI dashboards have replaced it, so familiarity is enough — deep mastery is rarely required. ## Note It is a *core* plugin (ships/binds for `site`), but unlike clean/jar/install/deploy it is not part of the default *build* lifecycle — it has its own.

  • Is the site lifecycle part of the default build lifecycle?
    No. maven-site-plugin has its own lifecycle (pre-site, site, post-site, site-deploy) invoked separately with mvn site; it is not triggered by mvn package/install/deploy.

saying these in an interview costs you the question

  • Saying mvn package or mvn install generates the site — it does not; the site lifecycle is separate.
  • Confusing site:deploy with the deploy phase that publishes artifacts.
  • Calling it the main documentation tool for modern app teams.

context

resolving links…