Wwhy

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 ./gradlew is enough.

Check what you have:

terminal
java -version
./gradlew --version

Add 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:

settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

Then apply the plugin and declare the repository it resolves the runtime from:

build.gradle.kts
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:

src/why/index.why
<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:

terminal
./gradlew whyRun

Open 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

TaskWhat it does
./gradlew whyRunServes src/why. Stops with Ctrl+C.
./gradlew whyCheckParses and checks every page, prints the page map, fails on problems. It is wired into check.
./gradlew jarCopies 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:

build.gradle.kts
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:

src/main/java/App.java
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.

terminal
git clone https://github.com/slayyyyer/why-lang.git
cd why-lang
./gradlew shadowJar
java -jar build/libs/why.jar ./site

The 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:

terminal
./gradlew publishToMavenLocal :why-gradle-plugin:publishToMavenLocal

CLI options

whyCheck and whyRun drive the same CLI, so these flags apply. whyRun passes --host, --port, --dev, --secure-cookies and --db from the extension.

OptionMeaning
siteFolder of .why files. Default: the current directory.
-p, --port NPort to listen on. Default: 8080.
--host HOSTInterface to bind. Default: 127.0.0.1 (loopback only). Use 0.0.0.0 only to expose it deliberately.
--db FILESQLite file. Default: data.db inside the site folder.
--devShow source excerpts, SQL errors and stack traces in 500 pages. Error pages are generic by default; details are always logged server-side.
--secure-cookiesMark 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, --helpUsage.

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.

src/why/schema.sql
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.