Move the user documentation to a Docusaurus site

The docs in docs/ become a Docusaurus site (pages in docs/content/),
published to GitHub Pages from main by .github/workflows/docs.yml and
built on devel and pull requests to catch broken links. The README is
reduced to a quick start that links to it.

The content was checked against the code: every property with its real
Maven and Gradle default, the startup scripts and launchers per
platform, bundling a JRE (customized, existing, other platforms, JDK
24+), code signing, templates, runtime JVM options, file associations,
samples and upgrading from 1.x. It fixes the errors in the old pages
(wrong defaults, Gradle bundleJre, sample names and paths, a broken XML
tag, old links) and documents properties that weren't (installationPath,
customLauncher, customInfoPlist, provisionProfile, msiUpgradeCode,
trademarks, signing fields, templates, duplicatesStrategy).

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

Author: fvarrui

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Docs
+
+# The site documents the latest release: it's deployed from main (and by hand from main); devel and pull requests only build it, to catch broken links
+on:
+  push:
+    branches: [ devel, main ]
+    paths: [ 'docs/**', '.github/workflows/docs.yml' ]
+  pull_request:
+    branches: [ devel, main ]
+    paths: [ 'docs/**', '.github/workflows/docs.yml' ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run build
+
+      - name: Upload site
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/build
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -32,3 +32,7 @@ hs_err_pid*
 
 ## More
 .DS_Store
+
+# Docusaurus (docs/)
+docs/node_modules/
+docs/.docusaurus/

.minispec/core/architecture.md

@@ -38,6 +38,6 @@ PackageMojo (Maven) | PackagePlugin + PackageTask (Gradle)
 - `src/main/java/.../javapackager/model/` — configuration model (`WindowsConfig`, `MacConfig`, `LinuxConfig`, `FileAssociation`, ...).
 - `src/main/java/.../javapackager/utils/` — helpers (files, commands, Velocity, JDK, icons, XML).
 - `src/main/resources/{linux,mac,windows}/` — Velocity templates, default icons and bundled native binaries (WinRun4J, `JavaLauncher.exe`, `rcedit-x64.exe`, `nativeJavaApplicationStub*`, `universalJavaApplicationStub.sh`).
-- `docs/` — user documentation for platform-specific properties and samples.
+- `docs/` — user documentation site (Docusaurus): pages in `docs/content/`, published to GitHub Pages from `main`.
 - `samples/hello-world/` — sample app packaged by the smoke tests, with the same settings in `pom.xml` and `build.gradle` (Maven writes to `target/`, Gradle to `build/`).
 - `.github/workflows/` and `.github/scripts/` — smoke tests, dependency submission and the per-platform checks.

.minispec/core/conventions.md

@@ -5,7 +5,7 @@
 - Build with the wrapper and a JDK 17+: `./gradlew build`. There are no unit tests: changes are verified by the smoke tests (`.github/workflows/smoke-tests.yml`), which package `samples/hello-world` on every platform.
 - Any change must keep working in both Maven and Gradle. Build-tool-specific code goes only in `maven/` or `gradle/`, behind `Context`.
 - The Gradle plugin uses no deprecated Gradle API, so it keeps working on the next Gradle major: `Boolean` task properties use `getX()`, not `isX()`; no `Task.getProject()` at execution time; `register()`, not `create()`. Check with `./gradlew -p samples/hello-world package --warning-mode all`.
-- A new configuration property is wired in: `PackagerSettings` (field + fluent setter + getter), `PackageMojo` (`@Parameter` + fluent call in `execute()`), `PackageTask` (annotated field + fluent call in `createPackager()` with `defaultIfNull(taskValue, extension.getX())`), and documented in `README.md` or `docs/*-specific-properties.md`.
+- A new configuration property is wired in: `PackagerSettings` (field + fluent setter + getter), `PackageMojo` (`@Parameter` + fluent call in `execute()`), `PackageTask` (annotated field + fluent call in `createPackager()` with `defaultIfNull(taskValue, extension.getX())`), and documented in the docs site: `docs/content/configuration/` (the common page or the platform one), with its real default for Maven and Gradle.
 - Platform-specific options go in `WindowsConfig`, `MacConfig` or `LinuxConfig`, not in `PackagerSettings`.
 - New artifacts are `ArtifactGenerator` subclasses. Platform and external-tool checks go in `skip()`, not in `doApply()`.
 - Template names and the variables they use are public API: users override them from `assetsDir`. Renaming a template or changing its variables is a breaking change.

.minispec/core/project.md

@@ -15,7 +15,7 @@ JavaPackager is a hybrid Maven/Gradle plugin, published as a single artifact (`i
 ## For whom
 
 - Java developers who want to distribute desktop apps without chaining several plugins.
-- Users configure it through `pom.xml` (goal `package`) or a Gradle `PackageTask`; see `README.md` and `docs/`.
+- Users configure it through `pom.xml` (goal `package`) or a Gradle `PackageTask`; see the docs site (`docs/content/`, published at https://javapackager.github.io/JavaPackager/).
 
 ## Goal
 

.minispec/features/docs-site.md

@@ -0,0 +1,31 @@
+# Documentation site
+
+## Goal
+
+Move the user documentation to a Docusaurus site in `docs/`, published on GitHub Pages, and keep `README.md` minimal.
+
+## Context
+
+- `README.md` (426 lines) holds the whole user guide: usage, artifacts, every property, assets, templates, runtime JVM options, snapshots, building and publishing.
+- `docs/` has per-platform property pages, Maven/Gradle samples, `manifest.md`, the Windows tools guide and a DMG image. Some content is outdated or wrong (old `fvarrui` links, bad Windows paths in samples, old bundle names, a broken XML closing tag) and some properties only link to the code (`fileAssociations`, `scripts`).
+- No GitHub Pages site yet. Node 26 and npm are available locally.
+- Decisions (user, 2026-10-11): publish from `main` (the site documents the latest release), no versioned docs.
+
+## Changes
+
+- Docusaurus (classic preset) project in `docs/`; pages in `docs/content/` (existing files moved with `git mv`; not Docusaurus' default `docs/docs`, user choice), images in `docs/static/img/`.
+- Site URL `https://javapackager.github.io/JavaPackager/`; workflow `.github/workflows/docs.yml` builds on push and pull requests to `devel`/`main` touching `docs/` and deploys on push to `main` (plus manual dispatch) with `actions/deploy-pages`.
+- Content, checked against the code (defaults, types, Maven and Gradle syntax):
+  - Introduction, getting started (Maven, Gradle), generated artifacts.
+  - Configuration reference: common properties, GNU/Linux, macOS, Windows, manifest, file associations, scripts.
+  - Guides: bundling a JRE (customized, full, existing, `additionalJlinkArgs`, other platforms, JDK 24+), icons and assets, templates, runtime JVM options, multiple executions and platforms, code signing, Windows tools, snapshots, upgrading from 1.x.
+  - Contributing: building the plugin, smoke tests, publishing.
+- `README.md`: what it is, quick start (Maven and Gradle), link to the site, maintainers wanted, apps packaged with it, license.
+- `CLAUDE.md` and conventions: documentation lives in `docs/content/` (new properties are documented there).
+
+## Acceptance
+
+- `npm run build` in `docs/` succeeds with no broken links.
+- The site is live at the URL above after a push to `main`.
+- Every property in `PackagerSettings` and the platform configs is documented with its real default.
+- `README.md` fits in one screen or two and links to the site.

CLAUDE.md

@@ -19,9 +19,12 @@ Use the wrapper (`./gradlew` or `gradlew.bat` on Windows).
 | `./gradlew publishToMavenLocal` | Install the plugin into `~/.m2` to test it from a sample Maven/Gradle project |
 | `./gradlew updateNativeJavaApplicationStub` | Re-download the native macOS launchers (`nativeJavaApplicationStub*`) into `src/main/resources/mac` from a [javapackager/nativeJavaApplicationStub](https://github.com/javapackager/nativeJavaApplicationStub) release |
 | `./gradlew updateWhyJavaLauncher` | Re-download `JavaLauncher.exe` into `src/main/resources/windows` |
+| `cd docs && npm install && npm start` | Preview the user documentation site (Docusaurus, Node.js 20+); `npm run build` fails on broken links |
 
 There are no unit tests, so there is no way to run a single test. Changes are verified by the smoke tests in `.github/workflows/smoke-tests.yml`, which run on every push to `devel`/`main`: they package `samples/hello-world` (one sample with both `pom.xml` and `build.gradle`) with Maven on GNU/Linux, Windows and macOS (each `macStartup`) and with Gradle on each platform, and run `.github/scripts/check-*-app.sh`. Build with a JDK 17+ (a JRE can't compile).
 
+User documentation is a Docusaurus site: pages in `docs/content/`, sidebar in `docs/sidebars.js`. It is published to GitHub Pages (https://javapackager.github.io/JavaPackager/) by `.github/workflows/docs.yml` on push to `main`, so it documents the latest release. `README.md` is only a quick start that links to it.
+
 `compileJava` triggers `generatePluginDescriptor`, which runs an embedded Maven against the generated POM to produce `META-INF/maven/plugin.xml` from the `@Mojo`/`@Parameter` annotations.
 
 Publishing uses a Central Portal user token in the `ossrhUsername`/`ossrhPassword` properties (`~/.gradle/gradle.properties`). Snapshots: `./gradlew publish` (Central Portal snapshots repo). Releases: `./gradlew releaseToCentral` (Portal OSSRH Staging API, then manual Publish in the Portal). The version is set in `build.gradle`.