2  Workflow

Day-to-day Babqua use comes down to two things: rendering documents and publishing the result.

2.1 Rendering

quarto render hello.qmd

This launches a single Babashka process for the duration of the render, evaluates every {.clojure .bb} block in order, and produces hello.html. State carries across blocks — defs and requires in block 1 are visible in block 2, just like a REPL session.

The bb process runs in your project root (the directory containing _quarto.yml, or the document’s directory if there’s no project config), so a sibling bb.edn is auto-loaded for deps and pods. You don’t need to do anything special — drop the deps you’d use in any bb script and they’re available inside notebook cells.

2.2 Preview mode

quarto preview hello.qmd

Quarto opens the rendered page in a browser and re-renders on every save. Each save spawns a fresh bb process — the same one-shot behavior as quarto render, just triggered automatically as you write.

For most documents, that’s all you need. If your document loads heavy pods or does expensive setup you’d rather not pay for on every save, the next section covers an optional persistent session.

2.3 Persistent bb session (optional)

For warm state across saves, start a long-lived bb session before running preview:

# Start once per session (typically before `quarto preview`)
bb _extensions/scicloj/bb/babqua-lifecycle.bb start

# Now run preview as normal — the filter detects the live REPL and
# routes evaluations through it.
quarto preview hello.qmd

# When you're done, tear it down.
bb _extensions/scicloj/bb/babqua-lifecycle.bb stop

While the persistent session is running, defs and requires carry across renders the way they would in any Clojure REPL — removing (def x 42) from a block doesn’t unbind x until you reset.

That’s the standard Clojure-ecosystem feel; if you’d rather have a fresh process per save (one-shot semantics, even with the session running), add this to your document’s frontmatter:

babqua:
  reset-on-render: true

Babqua then stops the running session before the render begins, this render runs as one-shot, and the persistent session stays down until you start it again.

A running session creates three state files in your project root: .babqua-pid and .babqua-nrepl-port (removed by stop), and .babqua-bb.log (the captured bb stdout/stderr — kept for post-mortem inspection, truncated on each start). Add all three to your .gitignore if they aren’t already covered.

2.4 Publishing to GitHub Pages

If your project is a Quarto book or website, you can publish it to GitHub Pages directly from your project directory:

quarto publish gh-pages

This renders the project and pushes the output to the gh-pages branch. GitHub Pages then serves it as a website. On first use, Quarto will create the branch and configure it for you.

See the Quarto publishing guide for more options, including custom domains and GitHub Actions automation.