Generate docs with AsciiDoctor and deploy

Add Maven POM with AsciiDoctor Maven Plugin (v3.2.0) to generate
HTML documentation from all README.adoc files to target/generated-docs.
Documentation includes images and maintains directory structure.

Add Maven Wrapper (3.9.11) for consistent Maven version across
environments and CI/CD pipelines.

Add new 'docs' workflow job that:
- Runs on Linux with Java 17 after successful build
- Generates HTML docs using './mvnw verify'
- Validates HTML with htmlSanityCheck plugin
- Deploys preview to Netlify for PRs and branches
- Deploys to GitHub Pages for main branch
- Creates index.html from README.html as landing page

Update .gitignore to exclude generated HTML files and target directory.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Introduced in the course of support-and-care/maven-support-and-care#137

Author: ascheman

.github/workflows/build.yml

@@ -164,4 +164,78 @@ jobs:
       shell: bash
       run: |
         echo "Environment:"
-        env | sort
+        env | sort
+
+  docs:
+    name: Generate and Deploy Documentation
+    runs-on: ubuntu-latest
+    needs: build
+    if: success()
+
+    permissions:
+      contents: read
+      pull-requests: write
+      pages: write
+      id-token: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up JDK 17
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+
+    - name: Generate documentation
+      run: ./mvnw verify
+
+    - name: Create index.html from README.html
+      run: cp target/generated-docs/README.html target/generated-docs/index.html
+
+    - name: Upload documentation artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: generated-docs
+        path: target/generated-docs
+        retention-days: 30
+
+    - name: Deploy to Netlify (Preview)
+      if: github.event_name == 'pull_request'
+      uses: nwtgck/actions-netlify@v3
+      with:
+        publish-dir: './target/generated-docs'
+        production-deploy: false
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        deploy-message: "Deploy from GitHub Actions - PR #${{ github.event.pull_request.number }}"
+        enable-pull-request-comment: true
+        enable-commit-comment: false
+        overwrites-pull-request-comment: true
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+
+    - name: Deploy to Netlify (Branch Preview)
+      if: github.event_name == 'push' && github.ref != 'refs/heads/main'
+      uses: nwtgck/actions-netlify@v3
+      with:
+        publish-dir: './target/generated-docs'
+        production-deploy: false
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        deploy-message: "Deploy from GitHub Actions - branch ${{ github.ref_name }}"
+        alias: ${{ github.ref_name }}
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+
+    - name: Upload to GitHub Pages
+      if: github.event_name == 'push'
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./target/generated-docs
+
+    - name: Deploy to GitHub Pages
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/deploy-pages@v4
+      id: deployment

.gitignore

@@ -17,5 +17,8 @@
 # User-specific environment configuration
 .envrc
 
-# Generated HTML (from AsciiDoc)
-*.html
+# Generated HTML and site output (from AsciiDoc)
+*.html
+
+# Maven artifacts
+target/

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip