(+ 1 2 3)6Hello, Babashka
This is the first Babashka-authored post on Clojure Civitas — and at the same time, a small walkthrough of how to author your own. The page is rendered with Babqua, a Quarto extension that evaluates {.clojure .bb} code blocks with Babashka during the render and replaces each block with its evaluated output. Kindly metadata controls how each value renders, the same convention Clay uses for Clojure documents.
Babqua is a sibling of Janqua, which does the same for Jank. The two extensions deliberately share authoring conventions — fence syntax, Kindly kinds, frontmatter shape — so a post can move between languages without rewriting its scaffolding.
A huge thanks to Michiel Borkent and the wider Babashka community for the runtime that makes this possible.
Why Babashka, on Civitas?
Babashka is a Clojure interpreter aimed at scripting and shell tasks. It starts in milliseconds, runs as a single binary, and includes a wide set of built-in libraries — JSON, Hiccup, HTTP, filesystem, process, and more. The pods ecosystem extends it further (SQLite, AWS, HTML parsing, …) without changing the deployment story.
For a notebook-style post, the appeal is reproducibility: a .qmd file plus a bb.edn (when it needs extra deps) is enough to render anywhere bb is installed. No JVM warm-up, no project skeleton.
Examples
Five small demonstrations, working up from a primitive expression to a recursive SVG fractal. Each one fits in a single block and exercises a different corner of Babashka’s standard library or Babqua’s rendering.
A first taste
Code blocks without Kindly metadata render as code output. The simplest possible block:
Annotate a value with ^:kind/... to tell Babqua how to render it:
^:kind/hiccup
[:div {:style "color: coral; font-size: 24px;"}
"Hello from Babashka!"]Hello from Babashka!
Mining the git log
The block below uses babashka.process/shell to invoke git log with a custom format string, splits the output line-by-line, and turns each line into a map. The result is a vector of recent commits, ready to chart:
(require '[babashka.process :as process]
'[clojure.string :as str])
(def commits
(->> (process/shell {:out :string}
"git" "log" "-200"
"--pretty=format:%h|%ad|%an"
"--date=format:%Y-%m")
:out
str/split-lines
(map #(zipmap [:hash :month :author]
(str/split % #"\|" 3)))))
(count commits)200State carries across blocks the way it does in any REPL session — commits defined above is visible below.
Aggregating into a per-month bar chart with Vega-Lite is one expression. Babqua serializes the value to JSON and Vega renders it client-side:
^:kind/vega-lite
{:data {:values commits}
:mark {:type "bar" :color "#d7161b"}
:encoding {:x {:field "month" :type "ordinal" :title "month"}
:y {:aggregate "count" :title "commits"}}
:width 480
:height 220}Walking the source tree
The next block uses babashka.fs to enumerate the top-level directories under src/ and count Clojure source files (.qmd, .clj, .cljc, .cljs) in each. Anchoring on the repo root via git rev-parse keeps the demo working from any working directory inside the checkout:
(require '[babashka.fs :as fs])
(def repo-root
(-> (process/shell {:out :string} "git" "rev-parse" "--show-toplevel")
:out str/trim))
(defn count-sources [dir]
(->> ["qmd" "clj" "cljc" "cljs"]
(mapcat #(fs/glob dir (str "**/*." %)))
count))
(def top-categories
(->> (fs/list-dir (fs/path repo-root "src"))
(filter fs/directory?)
(map (fn [dir] {:name (str (fs/file-name dir))
:count (count-sources dir)}))
(filter (comp pos? :count))
(sort-by (juxt (comp - :count) :name))
(take 8)))
top-categories({:name "scittle", :count 37} {:name "mentat_collective", :count 24} {:name "scicloj", :count 19} {:name "civitas", :count 14} {:name "math", :count 8} {:name "data_analysis", :count 5} {:name "data_visualization", :count 4} {:name "graph", :count 4})Rendering the result as a Mermaid diagram is a string template away. Kindly’s :kind/mermaid takes a vector-wrapped string:
^:kind/mermaid
[(let [;; prefix every node ID to avoid colliding with Mermaid keywords
;; (a category called "graph" would otherwise clash with `graph LR`)
node-id (fn [category-name]
(str "cat_" (str/replace category-name #"[^A-Za-z0-9_]" "_")))
edges (for [{:keys [name count]} top-categories]
(str " root --> " (node-id name)
"[\"" name "/ (" count ")\"]"))]
(str "graph LR\n root[\"src/\"]\n" (str/join "\n" edges)))]A small fractal, for joy
Hiccup happens to handle inline SVG just as readily as HTML — the tag is a keyword, the attributes are a map, and the children are nested vectors. Recursion gives us a Sierpinski triangle in a few lines:
(def sin60 (/ (Math/sqrt 3) 2))
(defn sierpinski [x y size depth]
(if (zero? depth)
[[:polygon
{:points (str x "," y " "
(+ x size) "," y " "
(+ x (/ size 2)) "," (- y (* size sin60)))}]]
(let [half (/ size 2)]
(mapcat (fn [[x y]] (sierpinski x y half (dec depth)))
[[x y]
[(+ x half) y]
[(+ x (/ half 2)) (- y (* half sin60))]]))))
^:kind/hiccup
[:svg {:xmlns "http://www.w3.org/2000/svg"
:viewBox "0 0 256 224"
:width 560
:fill "#d7161b"
:style "display:block;margin:0 auto"}
(sierpinski 0.0 222.0 256.0 7)]A recursive logo tree
Hiccup-as-SVG is not limited to primitive shapes. The block below builds a tree by recursion, but the leaves are <image> elements pointing at the same babashka-logo.png we embedded above. Each generation produces two children at ±32° from the parent’s heading (with a small random jitter), anchored at the parent’s two top corners so they spread outward like a Pythagoras tree. Five levels deep gives 63 logos. A seeded java.util.Random keeps the layout identical on every render.
(def ^java.util.Random random-source (java.util.Random. 42))
(defn jitter
"A random number drawn uniformly from [-radius, radius]."
[radius]
(- (* 2 radius (.nextDouble random-source)) radius))
(defn logo-tree
"Returns a flat seq of {:x :y :angle :scale} placements. Each call
yields one logo (centered above (anchor-x, anchor-y) and rotated by
`angle`), then recursively yields two children at the parent's
top-left and top-right corners, rotated ±32° from the parent's heading."
[anchor-x anchor-y angle scale depth]
(let [radians (Math/toRadians angle)
sine (Math/sin radians)
cosine (Math/cos radians)
half-height (* 100 scale) ;; logo is 200×200
center-x (+ anchor-x (* half-height sine))
center-y (- anchor-y (* half-height cosine))
tip-x (+ anchor-x (* 2 half-height sine))
tip-y (- anchor-y (* 2 half-height cosine))
side-x (* half-height cosine) ;; tip → top-corner
side-y (* half-height sine)
child-scale (* scale (+ 0.55 (jitter 0.05)))]
(cons {:x center-x :y center-y :angle angle :scale scale}
(when (pos? depth)
(concat
(logo-tree (- tip-x side-x) (- tip-y side-y)
(+ angle -32 (jitter 5)) child-scale (dec depth))
(logo-tree (+ tip-x side-x) (+ tip-y side-y)
(+ angle 32 (jitter 5)) child-scale (dec depth)))))))
(defn logo-svg
"Wrap one logo placement in an SVG `<g>` that translates, rotates, and
scales a `<image>` reference to the shared logo file."
[{:keys [x y angle scale]}]
[:g {:transform (str "translate(" x " " y ") rotate(" angle ") scale(" scale ")")}
[:image {:href "babashka-logo.png" :x -100 :y -100 :width 200 :height 200}]])
^:kind/hiccup
[:svg {:xmlns "http://www.w3.org/2000/svg"
:viewBox "-280 50 560 360"
:width 560
:style "display:block;margin:0 auto"}
(map logo-svg (logo-tree 0 380 0 0.6 5))]Where next?
This post was the first Babashka-authored page on Civitas. We’d love to see more. Babashka is well suited to small, scriptable demonstrations — fetching data, walking a directory, calling a pod, parsing a log — and posts that exercise one of those corners are exactly the kind of thing that makes the language and its ecosystem more discoverable.
If you hit something that doesn’t work, please open an issue on Babqua or on Civitas. Feedback shapes both.