Install
Two lines, then a page.
The io.github.slayyyyer.why Gradle plugin is on Maven Central. It packages src/why into your jar and gives you whyRun and whyCheck. There is no separate asset pipeline or database server to start.
Requirements
- JDK 21 or newer — the language, server and build all target 21.
- Gradle 8.5 or newer — the repository's wrapper pins 8.14.3, so
./gradlewis enough.
Check what you have:
java -version
./gradlew --versionAdd to Gradle
The plugin marker and the runtime are both on Maven Central, so list it for plugins and for dependencies. In settings.gradle.kts:
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}Then apply the plugin and declare the repository it resolves the runtime from:
plugins {
id("io.github.slayyyyer.why") version "0.2.0"
}
repositories {
mavenCentral()
}Two repositories, two jobs. pluginManagement resolves the plugin marker; repositories resolves io.github.slayyyyer:why-lang, which the plugin adds as an api dependency.
A first page
Pages live in src/why. Make the folder and add index.why in an editor:
<h1>Hello from a file</h1>
<p>No build step, no route table.</p>A file with no section labels is all view, so plain HTML is already a valid page. Start it:
./gradlew whyRunOpen http://localhost:8080/. Add about.why next to it and /about exists immediately. Copy a file in, refresh, it is live — every request re-reads and reparses the page.
No Gradle project yet? why new mysite writes a runnable folder of pages and prints the command that serves it; the repository's bin/why launcher runs the CLI jar, and deploy/ carries a container recipe.
Run, check, package
| Task | What it does |
|---|---|
./gradlew whyRun | Serves src/why. Stops with Ctrl+C. |
./gradlew whyCheck | Parses and checks every page, prints the page map, fails on problems. It is wired into check. |
./gradlew jar | Copies src/why into the jar at META-INF/why-site with a sorted META-INF/why-site.index. |
whyCheck reports unresolved imports and partials, duplicate defs, undefined function calls and URL collisions. It never touches the database. Wire it into CI by running ./gradlew check.
Database files stay out of the jar. Anything matching *.db, *.db-journal, *.db-wal or *.db-shm under src/why is excluded from both the jar and the index.
Configure
The why extension overrides the defaults:
why {
siteDir.set(layout.projectDirectory.dir("src/why"))
host.set("127.0.0.1")
port.set(8080)
diagnostics.set(true) // --dev for whyRun
secureCookies.set(false)
databaseFile.set(layout.projectDirectory.file("data.db"))
}whyRun uses the CLI default database, src/why/data.db, unless databaseFile is set. Keep development data out of the source tree by pointing databaseFile somewhere else, such as layout.buildDirectory.file("data.db").
Embed in Java
The plugin adds why-lang as an api dependency, so project code can serve the packaged site itself:
import why.Site;
import why.WhyServer;
Site site = Site.fromClasspath(); // or Site.fromClasspath(loader, dbFile)
WhyServer server = new WhyServer(site, 8080);
server.start();Site.fromClasspath() extracts the indexed resources to a temporary folder and bootstraps schema.sql when the database does not exist. Pass an explicit dbFile to keep data across restarts. Resources from multiple jars merge when their page names differ; a duplicate path is an error.
From source
To work on Why itself, clone the repository. One Gradle build produces the library, the plugin and the shaded CLI jar.
git clone https://github.com/slayyyyer/why-lang.git
cd why-lang
./gradlew shadowJar
java -jar build/libs/why.jar ./siteThe demo site starts on http://localhost:8080. To try a local build of the plugin against a consumer project instead, publish it locally and add mavenLocal() ahead of mavenCentral() in both repository blocks above:
./gradlew publishToMavenLocal :why-gradle-plugin:publishToMavenLocalCLI options
whyCheck and whyRun drive the same CLI, so these flags apply. whyRun passes --host, --port, --dev, --secure-cookies and --db from the extension.
| Option | Meaning |
|---|---|
site | Folder of .why files. Default: the current directory. |
-p, --port N | Port to listen on. Default: 8080. |
--host HOST | Interface to bind. Default: 127.0.0.1 (loopback only). Use 0.0.0.0 only to expose it deliberately. |
--db FILE | SQLite file. Default: data.db inside the site folder. |
--dev | Show source excerpts, SQL errors and stack traces in 500 pages. Error pages are generic by default; details are always logged server-side. |
--secure-cookies | Mark the session cookie Secure when serving behind TLS. |
check [site] | Parse and check every page, report problems, print the page map, exit 1 on problems. Does not serve or touch the database. |
-h, --help | Usage. |
The database
If the database file is missing when the server starts and the site folder contains schema.sql, the script runs once. A small site can therefore be a folder you can copy anywhere.
create table if not exists notes (
id integer primary key,
body text not null,
created_at text not null
);There is no migration runner. In development, deleting the database and letting schema.sql recreate it is the whole story. In anything you care about, keep the schema and migrations outside Why.
Running it somewhere
The artifact is your application jar with the pages inside it, or build/libs/why.jar plus a site folder for the CLI. On a server, run it under whatever supervises processes, put it behind a reverse proxy if it is exposed, keep the SQLite database outside the site folder, and keep backups of the SQLite file.
Not production-hardened. There is no TLS, authentication, rate limiting or sandbox. Pages can run arbitrary SQL and read the database. Run it on a trusted network, or treat it as a prototype.
Troubleshooting
“Plugin [id: 'io.github.slayyyyer.why', version: '0.2.0'] was not found”
The marker lives on Maven Central, not the Plugin Portal. Add mavenCentral() to pluginManagement.repositories in settings.gradle.kts.
“Could not find io.github.slayyyyer:why-lang:0.2.0”
The plugin adds the runtime as a dependency. Add mavenCentral() to the project's repositories block.
whyRun does nothing
Both tasks skip when the site directory is missing. Create src/why, or point why { siteDir.set(...) } at your folder.
“Address already in use”
Another process owns the port. Set why { port.set(3000) }, or add --port 3000 to the CLI.
“cannot find import 'header'”
The import is a bare name. It looks for header.why next to the importing page, then in the site root. Check the spelling and the folder. A leading _ is allowed and means import-only.
/_header answers 404
That is the convention: files whose name starts with _ can be imported but are never served. Use {{> _header}} from a page.
I changed schema.sql and nothing happened
The script only runs when the database file is missing. Stop the server, delete the database, and start again.
“java: command not found” or the wrong version
Install JDK 21+ and check java -version. Gradle uses whatever JDK it runs on unless you set a toolchain.
The page is blank
Check the server log: parse and runtime errors are printed with file:line, and with diagnostics.set(true) the browser gets a 500 page with the source excerpt. whyCheck catches most problems before the request.
Next: the language and page format, or copy a recipe.