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 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.7 Next steps

  • See Workflow for render vs preview modes and publishing
  • See Kindly kinds for controlling how each result renders (HTML, charts, diagrams, math, …)
  • See Authoring Babqua documents for code-block attributes and per-block options
  • See the Demo for evaluated examples