Recipes
Small pages that do real work.
Each recipe is a file or two, not a project. They assume a Gradle project with the io.github.slayyyyer.why plugin, pages under src/why, and ./gradlew whyRun serving them; see install if you have not started one yet.
Hello, file
a page with no sections · the URL is the filename
Put a plain HTML file in the site folder. A file with no imports:, controller: or view: labels is all view.
<h1>Hello from a file</h1>
<p>No build step, no route table.</p>Open /hello (or /hello.why). There is no registration step; the file is the route.
A shared layout
imports · partials · import-only files
A leading underscore makes a file importable but not reachable. Use it for chrome you never want to serve on its own.
view:
<header class="site">
<strong>My site</strong>
<nav>
<a href="/">home</a>
<a href="/about">about</a>
</nav>
</header>imports:
_header
view:
{{> _header}}
<h1>Home</h1>
<p>The header is a file, not a component.</p>/_header and /_header.why both answer 404; {{> _header}} still works. Imports are transitive, so a header can import its own footer.
A list from SQLite
schema.sql · db.query · each/else
Drop a schema next to the pages. It runs once, when the database file does not exist.
create table if not exists notes (
id integer primary key,
body text not null,
created_at text not null
);imports:
_header
controller:
notes = db.query("select * from notes order by id desc")
view:
{{> _header}}
<h1>Notes</h1>
{{#each notes}}
<article>
<p>{{it.body}}</p>
<p class="meta">{{it.created_at}}</p>
</article>
{{else}}
<p>No notes yet.</p>
{{/each}}Rows are hashes keyed by column label, so {{it.body}} works. The query returns a list; {{else}} handles the empty case.
A query parameter
params · db.get · escaped output
Query parameters are strings. Bind one into a prepared statement; never concatenate it into SQL.
controller:
post = db.get("select * from posts where id = ?", params.id)
view:
<h1>{{post.title}}</h1>
{{{post.body}}}/post?id=3 gives params.id == "3". {{post.title}} is escaped; {{{post.body}}} is raw. Only use the raw form for content you trust.
A guestbook
POST · bound insert · flash · redirect
One page reads and writes. The POST branch validates, inserts, queues a one-shot notice, and redirects; the GET renders the list and the form.
create table if not exists guestbook (
id integer primary key,
name text not null,
message text not null,
created_at text not null
);imports:
_header
controller:
if request.method == "POST"
name = form.name.strip
message = form.message.strip
if name != "" and message != ""
db.exec("insert into guestbook (name, message, created_at) values (?, ?, datetime('now'))", name, message)
flash.set("notice", "Thanks — your note is in the book.")
redirect("/guestbook")
end
end
entries = db.query("select * from guestbook order by id desc limit 50")
title = "Guestbook"
view:
{{> _header}}
<h1>{{title}}</h1>
{{#if flash.notice}}<p class="note">{{flash.notice}}</p>{{/if}}
<form method="post" action="/guestbook">
<label>Name <input name="name" maxlength="60" required></label>
<label>Message <textarea name="message" rows="3" maxlength="500" required></textarea></label>
<button type="submit">Sign the guestbook</button>
</form>
{{#each entries}}
<article>
<p class="meta"><strong>{{it.name}}</strong> · {{it.created_at}}</p>
<p>{{it.message}}</p>
</article>
{{else}}
<p>No entries yet. Be the first.</p>
{{/each}}The flash is keyed by a why_session cookie, shown on the next page request, and then gone. Empty fields fall through silently — the demo's validation is deliberately minimal.
Check in CI
why check · GitHub Actions
why check parses and checks every page and exits 1 on problems, so it drops into a workflow with no extra plugin.
name: check
on:
push:
pull_request:
jobs:
why:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "21"
- run: ./gradlew whyCheckThat is the whole check: no server, no database, no port. whyCheck reports imports, partials, duplicate defs, undefined free-function calls and URL collisions, then prints a page map. It also runs as part of ./gradlew check.
More detail lives in Using Why. The demo site in the repository is the full version of the guestbook recipe.