docs: JavaDoc site (javadoc branch + javadoc.io)

.github/workflows/pages-repo.yml

@@ -3,7 +3,9 @@ name: publish-public-repo
 # Retired. This workflow used to git-push snapshots to Pinont/singularity-maven
 # (maven.pinont.me). That path is closed:
 #   - Snapshots live on GitHub Packages (build.yml, GITHUB_TOKEN).
-#   - maven.pinont.me is a frozen Pages archive — do not git-push it from CI.
+#   - maven.pinont.me is a frozen Pages archive — do not git-push it from CI
+#     (no Maven layout, no JavaDoc). Public JavaDoc HTML is published by
+#     publish-javadoc.yml to the `javadoc` branch of this repo.
 #   - Releases go to Maven Central via release.yml
 #     (SONATYPE_USERNAME / SONATYPE_PASSWORD).
 #   - Central Portal does not accept SNAPSHOT uploads.
@@ -22,4 +24,5 @@ jobs:
           echo "publish-public-repo is retired."
           echo "Snapshots: GitHub Packages (build.yml)."
           echo "maven.pinont.me is a frozen Pages archive."
+          echo "JavaDoc HTML: publish-javadoc.yml -> javadoc branch."
           echo "Releases: Maven Central via release.yml."

.github/workflows/publish-javadoc.yml

@@ -0,0 +1,149 @@
+name: publish-javadoc
+
+# Generates JavaDoc HTML for public consumption.
+#
+# Hosting (after pages-repo retirement): there is no usable GitHub Actions
+# secret for pushing to Pinont/singularity-maven. maven.pinont.me is a frozen
+# Pages archive — this workflow does not git-push it and does not invent a
+# MAVEN_REPO_TOKEN. GitHub Pages on this repo is also off-limits
+# (pinont.github.io/SingularityLib is captured by the pinont.me domain).
+#
+# Instead:
+#   1. Always generate HTML and upload it as a workflow artifact.
+#   2. On push to main (and workflow_dispatch), publish the HTML to the
+#      `javadoc` branch of THIS repo with GITHUB_TOKEN (no extra secret).
+#   3. maven-javadoc-plugin still attaches the javadoc jar for Central /
+#      GitHub Packages. Release JavaDoc is also on javadoc.io once Central
+#      has the version.
+#
+# Browse SNAPSHOT/latest: https://cdn.jsdelivr.net/gh/Pinont/SingularityLib@javadoc/
+# Tree:                  https://github.com/Pinont/SingularityLib/tree/javadoc
+#
+# To land HTML on maven.pinont.me/javadoc/ later, Nont needs a PAT with
+# contents:write on Pinont/singularity-maven. Do not wire that until it exists.
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: publish-javadoc-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+
+      - name: Install annotation processor module
+        run: mvn -q install -DskipTests -f singularitylib-processor/pom.xml
+
+      - name: Resolve project version
+        id: ver
+        run: |
+          VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)
+          VERSION=$(printf '%s' "${VERSION}" | tr -d '\r\n' | sed 's/[[:space:]]*$//')
+          case "${VERSION}" in
+            ''|*..*|*"/"*|*"\\"*)
+              echo "Refusing unusable project.version: '${VERSION}'" >&2
+              exit 1
+              ;;
+          esac
+          printf 'version=%s\n' "${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate JavaDoc HTML
+        run: mvn -q javadoc:javadoc -DskipTests
+
+      - name: Locate JavaDoc output
+        id: javadoc
+        run: |
+          if [ -d target/site/apidocs ]; then
+            printf 'dir=%s\n' "target/site/apidocs" >> "$GITHUB_OUTPUT"
+          elif [ -d target/reports/apidocs ]; then
+            printf 'dir=%s\n' "target/reports/apidocs" >> "$GITHUB_OUTPUT"
+          else
+            echo "JavaDoc output not found under target/site or target/reports" >&2
+            find target -type d -name apidocs || true
+            exit 1
+          fi
+
+      - name: Stage site (landing + version + latest)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          JAVADOC_DIR: ${{ steps.javadoc.outputs.dir }}
+        run: |
+          set -euo pipefail
+          SITE="${{ github.workspace }}/javadoc-site"
+          mkdir -p "${SITE}/${VERSION}" "${SITE}/latest"
+          cp docs/index.html "${SITE}/index.html"
+          cp -R "${JAVADOC_DIR}/." "${SITE}/${VERSION}/"
+          cp -R "${JAVADOC_DIR}/." "${SITE}/latest/"
+          touch "${SITE}/.nojekyll"
+
+      - name: Upload JavaDoc HTML artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: javadoc-html
+          path: javadoc-site
+          if-no-files-found: error
+
+  publish:
+    # Never publish from pull requests. workflow_dispatch may run off main.
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
+    needs: generate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download JavaDoc HTML artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: javadoc-html
+          path: javadoc-site
+
+      - name: Publish to javadoc branch
+        env:
+          VERSION: ${{ needs.generate.outputs.version }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          SITE="${{ github.workspace }}/javadoc-site"
+          git clone --depth 1 "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git" repo
+          cd repo
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git ls-remote --exit-code --heads origin javadoc >/dev/null; then
+            git fetch --depth 1 origin javadoc
+            git checkout -B javadoc origin/javadoc
+          else
+            git checkout --orphan javadoc
+            git rm -rf --quiet . >/dev/null 2>&1 || true
+            git clean -fdx >/dev/null 2>&1 || true
+          fi
+          mkdir -p "${VERSION}" latest
+          cp "${SITE}/index.html" index.html
+          cp "${SITE}/.nojekyll" .nojekyll
+          rm -rf "${VERSION}" latest
+          mkdir -p "${VERSION}" latest
+          cp -R "${SITE}/${VERSION}/." "${VERSION}/"
+          cp -R "${SITE}/latest/." latest/
+          git add -A
+          if git diff --cached --quiet; then
+            echo "No javadoc changes"
+            exit 0
+          fi
+          git commit -m "docs: javadoc singularitylib ${VERSION} (${{ github.sha }})"
+          git push origin javadoc

README.md

@@ -1,6 +1,8 @@
 # SingularityLib
 
-[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml)
+[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml) [![JavaDoc](https://img.shields.io/badge/docs-JavaDoc-e0a54b)](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0)
+
+**Docs / JavaDoc:** [javadoc.io (2.0.0)](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0) · [latest from `main`](https://cdn.jsdelivr.net/gh/Pinont/SingularityLib@javadoc/latest/) · [`javadoc` branch](https://github.com/Pinont/SingularityLib/tree/javadoc)
 
 A fork of [ExperienceLib](https://github.com/pinont/ExperienceLib)
 
@@ -50,6 +52,8 @@ SingularityLib is published to **Maven Central** — no repository block needed
 
 ### Snapshots (dev/pre-release)
 
+Live SNAPSHOT jars are published to [GitHub Packages](https://github.com/Pinont/SingularityLib/packages) (`build.yml`, `GITHUB_TOKEN`). `https://maven.pinont.me` is a frozen Pages archive and is not updated from CI.
+
 ```xml
 <repositories>
   <repository>

docs/index.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SingularityLib — Docs</title>
+  <meta name="description" content="SingularityLib JavaDoc and install coordinates. A PaperMC plugin development library.">
+  <style>
+    :root {
+      --bg: #0f1419;
+      --panel: #171e27;
+      --ink: #e8eef4;
+      --muted: #9aa8b5;
+      --line: #2a3542;
+      --accent: #e0a54b;
+      --accent-ink: #1a1408;
+      --link: #7ec8e8;
+    }
+    * { box-sizing: border-box; }
+    html, body { margin: 0; padding: 0; }
+    body {
+      font-family: "Segoe UI", system-ui, sans-serif;
+      background: var(--bg);
+      color: var(--ink);
+      line-height: 1.55;
+      min-height: 100vh;
+    }
+    main {
+      max-width: 44rem;
+      margin: 0 auto;
+      padding: 3.5rem 1.25rem 4rem;
+    }
+    .eyebrow {
+      font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      font-size: 0.75rem;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      color: var(--accent);
+      margin: 0 0 0.75rem;
+    }
+    h1 {
+      font-size: 2.15rem;
+      font-weight: 600;
+      letter-spacing: -0.02em;
+      margin: 0 0 0.75rem;
+    }
+    .lead { color: var(--muted); margin: 0 0 1.75rem; }
+    .actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.6rem;
+      margin: 0 0 2.25rem;
+    }
+    a.btn {
+      display: inline-flex;
+      align-items: center;
+      text-decoration: none;
+      font-weight: 500;
+      font-size: 0.95rem;
+      padding: 0.55rem 0.95rem;
+      border-radius: 6px;
+      border: 1px solid var(--line);
+      color: var(--ink);
+      background: var(--panel);
+    }
+    a.btn.primary {
+      background: var(--accent);
+      color: var(--accent-ink);
+      border-color: var(--accent);
+    }
+    a.btn:hover { filter: brightness(1.08); }
+    section {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 10px;
+      padding: 1.15rem 1.2rem 1.05rem;
+      margin: 0 0 1rem;
+    }
+    h2 {
+      font-size: 0.95rem;
+      font-weight: 600;
+      margin: 0 0 0.65rem;
+    }
+    p { margin: 0 0 0.7rem; }
+    p:last-child { margin-bottom: 0; }
+    code, pre {
+      font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      font-size: 0.85rem;
+    }
+    pre {
+      margin: 0;
+      overflow-x: auto;
+      background: #0c1015;
+      border: 1px solid var(--line);
+      border-radius: 6px;
+      padding: 0.85rem 1rem;
+      color: var(--ink);
+    }
+    a { color: var(--link); }
+    ul { margin: 0.25rem 0 0; padding-left: 1.2rem; color: var(--muted); }
+    li { margin: 0.2rem 0; }
+    footer {
+      margin-top: 2rem;
+      color: var(--muted);
+      font-size: 0.85rem;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <p class="eyebrow">PaperMC · JDK 25 · Maven Central</p>
+    <h1>SingularityLib</h1>
+    <p class="lead">
+      Core API library for Paper plugins: commands, config, GUI, items, entities,
+      compile-time auto-registration, database helpers, and Discord JDA bootstrap.
+    </p>
+
+    <div class="actions">
+      <a class="btn primary" href="./latest/index.html">Browse JavaDoc</a>
+      <a class="btn" href="https://github.com/Pinont/SingularityLib#installation-maven">Install (README)</a>
+      <a class="btn" href="https://central.sonatype.com/artifact/io.github.pinont/singularitylib">Maven Central</a>
+    </div>
+
+    <section>
+      <h2>Maven Central coordinates</h2>
+      <p>Releases are on Central — no extra repository block. Scope <code>provided</code>; the lib loads as its own server plugin.</p>
+      <pre><code>&lt;dependency&gt;
+  &lt;groupId&gt;io.github.pinont&lt;/groupId&gt;
+  &lt;artifactId&gt;singularitylib&lt;/artifactId&gt;
+  &lt;version&gt;2.0.0&lt;/version&gt;
+  &lt;scope&gt;provided&lt;/scope&gt;
+&lt;/dependency&gt;</code></pre>
+    </section>
+
+    <section>
+      <h2>JavaDoc</h2>
+      <p>
+        HTML is generated from <code>src/main/java</code> and published to the
+        <code>javadoc</code> branch of this repository (no extra CI secret).
+        Release docs also live on javadoc.io once Central has the version.
+      </p>
+      <ul>
+        <li><a href="./latest/index.html">Latest from <code>main</code></a></li>
+        <li>Per-version copies live alongside this page (folder named after the pom version)</li>
+        <li>Release:
+          <a href="https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0">javadoc.io (2.0.0)</a>
+        </li>
+      </ul>
+    </section>
+
+    <section>
+      <h2>Snapshots</h2>
+      <p>
+        Dev builds: <code>io.github.pinont:singularitylib:2.0.0-SNAPSHOT</code> from
+        <a href="https://github.com/Pinont/SingularityLib/packages">GitHub Packages</a>.
+        <code>maven.pinont.me</code> is a frozen Pages archive.
+        Full install notes, including the bootstrap <code>paper-plugin.yml</code> snippet, are in the
+        <a href="https://github.com/Pinont/SingularityLib#installation-maven">README</a>.
+      </p>
+    </section>
+
+    <footer>
+      <a href="https://github.com/Pinont/SingularityLib">GitHub</a>
+      ·
+      <a href="https://github.com/Pinont/SingularityLib/blob/main/LICENSE">MIT</a>
+    </footer>
+  </main>
+</body>
+</html>

docs/javadoc-root.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Singularity JavaDoc</title>
+  <meta http-equiv="refresh" content="0; url=singularitylib/">
+  <link rel="canonical" href="singularitylib/">
+</head>
+<body>
+  <p>JavaDoc: <a href="singularitylib/">SingularityLib</a></p>
+</body>
+</html>