Babqua

Babashka code in Quarto documents

Overview

Babqua is a Quarto extension for writing Babashka code in visual documents. Each {.clojure .bb} block in a .qmd file is evaluated by Babashka during rendering, producing code output, charts, diagrams, tables, or computed HTML.

Charts render via Plotly, Vega-Lite, ECharts, Cytoscape, or Highcharts; diagrams via Mermaid and Graphviz; tables as HTML. Rendering follows the Kindly convention, the same way Clay handles Clojure docs.

Babqua is the sibling of Janqua, which targets Jank. Same Quarto-filter pattern, same Kindly vocabulary, different host language.

Note

Babqua is at an experimental stage. Things may change, and some rough edges are expected. Feedback, bug reports, and ideas are very welcome — please open an issue on GitHub or reach out on the Clojurians Zulip chat.

What is Quarto?

Quarto is an open-source publishing system for technical documents — widely used in scientific communities for blog posts, books, academic papers, and reproducible research. You write .qmd (Quarto Markdown) files mixing prose and code, and Quarto renders them to HTML, PDF, slides, and other formats.

Quarto has been used in multiple Clojure projects, most often through Clay — a Clojure tool that generates Quarto markdown from Clojure namespaces.

Quarto supports several project types:

  • Single documents — a standalone .qmd file
  • Websites — multiple pages with navigation, like a documentation site
  • Books — chapters rendered as a navigable book (like this one)

What is Babashka?

Babashka is a Clojure runtime built for scripting. It ships with a curated set of libraries (HTTP, JSON, hiccup, EDN, processes, …) and supports pods for dropping in things like SQLite, AWS, HTML parsing, and more, without requiring a JVM.

Use Babqua for…

  • Tutorials and documentation — about Babashka itself or libraries built on it, with live-evaluated examples woven into the narrative
  • Research reports and data analysis — figures, tables, math, and prose in a single reproducible document
  • Interactive exploration — iterate quickly with quarto render on save, or use quarto preview for live re-rendering (with an optional persistent bb session for warm state — see Workflow)
  • Sharing on Clojure Civitas — Babashka posts on the Clojure community’s collaborative space

Clojure ecosystem connection

Clay generates Quarto markdown from Clojure namespaces, then uses Quarto as a rendering engine to produce HTML pages, books, and slideshows — the established path for JVM Clojure documents in the Quarto world.

Babqua takes a different approach: rather than generating Quarto markdown from a namespace, the Quarto filter evaluates {.clojure .bb} blocks embedded directly in .qmd files. It follows the Kindly convention for rendering annotations, so familiar Kindly metadata patterns apply when authoring Babashka documents.

The two approaches are complementary, both following the Kindly convention.

How it works

  1. You write a .qmd file with {.clojure .bb} code blocks
  2. When Quarto renders the document, the Babqua filter intercepts these blocks
  3. A single Babashka process evaluates all of them in order, in the project root (or the document’s directory for standalone files), so a sibling bb.edn is auto-loaded for deps and pods
  4. Results are rendered into the document — as code output, HTML, charts, diagrams, or markdown — based on Kindly kinds
^:kind/hiccup
[:div {:style "color: coral; font-size: 24px;"}
  "Hello from Babashka!"]
Hello from Babashka!

See Getting Started to try it out, or jump to the Demo to see evaluated examples.

Roadmap

  • More Kindly kinds — :kind/dataset, :kind/image are the next candidates after the v1 set (the Kindly kinds page lists what’s already in)
  • Pod-driven demos — SQLite, AWS, HTML parsing in a notebook without a JVM
  • Clay support for Babashka — namespace-as-notebook experience, where .clj source files render as documents without writing .qmd by hand

Chapters

  • Getting Started — prerequisites, installation, first document, rendering
  • Workflow — render and preview modes, publishing
  • Kindly kinds — controlling how a value renders (HTML, charts, diagrams, math, …)
  • Authoring Babqua documents — code-block attributes, per-block options, document-level Quarto features
  • How It Works — architecture, three-pass filter, bb invocation, runtime
  • Demo — evaluated examples of all output kinds
  • Contributing — repo layout, local rendering, the symlink convention (for people working on Babqua itself)