◐ Shell
clean mode source ↗

javaevolved.github.io/html-generators/README.md at main · javaevolved/javaevolved.github.io

This folder contains the build scripts that generate all HTML detail pages and site/data/snippets.json from the JSON source files in content/.

Files

File Description
generate.java JBang script (Java 25) — primary generator
generate.py Python equivalent — produces identical output
generate.jar Pre-built fat JAR (no JBang/JDK setup needed)
build-cds.sh Script to build a platform-specific AOT cache

Benchmark

See benchmark/README.md for performance comparisons across all four execution methods (AOT, Fat JAR, JBang, Python).

Running

Option 1: Fat JAR (fastest, no setup)

java -jar html-generators/generate.jar

Requires only a Java 25+ runtime — no JBang installation needed.

Option 2: Fat JAR with AOT cache (fastest possible)

# One-time: build the AOT cache (~21 MB, platform-specific)
./html-generators/build-cds.sh

# Subsequent runs use the cache
java -XX:AOTCache=html-generators/generate.aot -jar html-generators/generate.jar

The AOT cache (Java 25, JEP 514/515) pre-loads classes from a training run, reducing startup time by ~30%. The cache is platform-specific and is not committed to git — regenerate it after changing the JAR or JDK version.

Option 3: JBang (for development)

jbang html-generators/generate.java

Requires JBang and Java 25+.

Option 4: Python

python3 html-generators/generate.py

Requires Python 3.8+.

Rebuilding the fat JAR

After modifying generate.java, rebuild the fat JAR:

jbang export fatjar --output html-generators/generate.jar html-generators/generate.java

This produces a self-contained ~2.2 MB JAR with all dependencies (Jackson) bundled. The build-generator.yml GitHub Action does this automatically when generate.java changes.

CI/CD Workflows

Two GitHub Actions workflows automate the build and deploy pipeline:

  1. build-generator.yml — Triggered when generate.java changes on main. Uses JBang to rebuild the fat JAR and commits the updated generate.jar back to the repository.

  2. deploy.yml — Triggered when content, templates, the JAR, or site assets change on main. Runs java -jar html-generators/generate.jar to regenerate all HTML pages, snippets.json, and index.html, then deploys the site/ folder to GitHub Pages.

This means the deploy workflow always uses the pre-built fat JAR (no JBang required at deploy time), and the JAR stays in sync with the source automatically.