1  Getting Started

Babqua is currently developed and tested on Linux. macOS hasn’t been verified — if you try it, please open an issue with what you find.

1.1 Prerequisites

  1. Quarto — the publishing system
  2. Babashka — the Clojure scripting runtime

Verify both are available:

quarto --version
bb --version

1.2 Create a project

mkdir my-bb-doc
cd my-bb-doc

If you want to bring in extra libraries or pods later, drop a bb.edn here. Babashka auto-loads it from the directory the filter runs in — for a standalone document like this one, that’s the document’s directory; for a Quarto book or website, it’s the project root (the directory with _quarto.yml).

1.3 Install the extension

Run this inside your project directory — it creates an _extensions/ folder there:

quarto add scicloj/babqua

Quarto will ask you to confirm — type y and press Enter.

Sense check that the filter files landed:

ls _extensions/scicloj/bb/

You should see _extension.yml, babqua.lua, babqua.css, runtime.bb, and the two scripts used by preview mode — babqua-lifecycle.bb and babqua-nrepl-client.bb.

1.4 Write a document

Create a file called hello.qmd:

---
title: "Hello Babashka"
filters:
  - bb
---

```{.clojure .bb}
(+ 1 2 3)
```

```{.clojure .bb}
^:kind/hiccup
[:div {:style "color: coral; font-size: 24px;"} "Hello from Babashka!"]
```

Note the {.clojure .bb} syntax: .clojure enables syntax highlighting (in editors and rendered output), and .bb tells the Babqua filter to evaluate the block. Both use dot prefixes — that’s Pandoc class syntax.

The filters: [bb] in the frontmatter (the YAML header at the top of the file, between the --- markers) tells Quarto to use the Babqua filter.

1.5 Render it

quarto render hello.qmd

This launches a single Babashka process, evaluates the code blocks in order, and produces hello.html.

1.6 Preview mode

For iterative writing, use:

quarto preview hello.qmd

Quarto opens the rendered page in a browser and re-renders on every save, so you see your changes as you write. By default each save spawns a fresh bb process; for documents that load heavy pods or do expensive setup, Babqua can keep a persistent bb session warm across saves so you only pay the startup cost once.

See Workflow for the persistent-session commands and the reset-on-render option.

1.7 Trust model

Rendering a Babqua document evaluates its .bb blocks as ordinary Babashka code, with full filesystem, network, and shell access. Treat rendering an untrusted .qmd the same as running its author’s bb script on your machine — the same trust model as Clay or any other notebook environment that evaluates user code.

1.8 Next steps