Installation Guide

Detailed installation and configuration guide for Maven Skin.

System Requirements

Mandatory

  • Maven: 3.9+ (latest recommended)
  • Java: 25 (latest recommended)
  • Modern Web Browser: Chrome, Firefox, Safari, or Edge (for viewing generated site)

Optional

  • Git: For version control (if deploying to GitHub Pages)
  • GitHub Account: For hosting documentation on GitHub Pages

Verify Installation

Check your Maven version:

mvn --version

Expected output:

Apache Maven 3.9.x (or later)
...

Check your Java version:

java --version

Expected output:

java 25.x (or later)
...

If either version is too old, please upgrade before proceeding.

Configuration

Basic Site Configuration

Create src/site/site.xml to configure your site’s navigation:

<?xml version="1.0" encoding="UTF-8"?>
<project name="My Project" xmlns="http://maven.apache.org/DECORATION/1.8.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0
         http://maven.apache.org/xsd/decoration-1.8.0.xsd">

  <!-- Add the Maven Skin here -->
  <skin>
    <groupId>pro.verron</groupId>
    <artifactId>maven-skin</artifactId>
    <version>1.0</version>
  </skin>

  <body>
    <menu name="Documentation">
      <item name="Home" href="index.html"/>
      <item name="Getting Started" href="getting-started.html"/>
      <item name="Installation" href="installation.html"/>
      <item name="Examples" href="examples.html"/>
    </menu>

    <menu name="Community">
      <item name="GitHub" href="https://github.com/yourname/yourproject"/>
      <item name="Issues" href="https://github.com/yourname/yourproject/issues"/>
    </menu>
  </body>
</project>

Maven Site Plugin Configuration

Add this to your pom.xml <build><plugins> section:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.22.0</version>
  <configuration>
    <generateSitemap>true</generateSitemap>
    <asciidoc>
      <attributes>
        <source-highlighter>coderay</source-highlighter>
        <coderay-css>style</coderay-css>
      </attributes>
    </asciidoc>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.reporting</groupId>
      <artifactId>maven-reporting-exec</artifactId>
      <version>2.0.0</version>
    </dependency>
    <dependency>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>3.2.0</version>
    </dependency>
    <dependency>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-parser-doxia-module</artifactId>
      <version>3.2.0</version>
    </dependency>
  </dependencies>
</plugin>

Local Site Generation

Generate Your Site

mvn clean site

Maven will: * Clean previous build artifacts * Generate documentation from src/site/asciidoc/ * Apply Maven Skin styling * Create the site in target/site/

View Locally

# macOS
open target/site/index.html

# Linux
xdg-open target/site/index.html

# Windows
start target/site/index.html

Or open target/site/index.html manually in your browser.

Browser Caching

The generated site uses modern caching strategies:

  • CSS and JavaScript files are minified
  • Static assets have long cache headers
  • No external dependencies for core functionality

Response Size

Maven Skin is lightweight:

  • Minimal CSS (~20KB gzipped)
  • Minimal JavaScript (~10KB gzipped)
  • No heavy frameworks or dependencies

Updates and Maintenance

Update Maven Skin

To update to a newer version:

<skin>
  <groupId>pro.verron</groupId>
  <artifactId>maven-skin</artifactId>
  <version>1.1</version>  <!-- Update version number -->
</skin>

Then rebuild:

mvn clean site

Clear Cache

If you experience odd styling issues after update:

# Remove Maven cache
rm -rf ~/.m2/repository/pro/verron/maven-skin

# Remove site build
mvn clean

# Rebuild
mvn site

# Clear browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)

Next Steps

  • See Getting Started for quick setup
  • See Examples for documentation patterns
  • Create your first documentation page in src/site/asciidoc/index.adoc
  • Deploy to GitHub Pages with automatic workflow

Happy documenting! 📚