7  Contributing

Notes for people working on Babqua itself. If you’re here to use Babqua, start with Getting Started instead.

7.1 Repo layout

  • _extensions/bb/ — source of truth for the published extension. The Lua filter (babqua.lua), bb-side runtime (runtime.bb), the preview-mode lifecycle script (babqua-lifecycle.bb) and its companion nREPL client (babqua-nrepl-client.bb, invoked per render when persistent mode is active), stylesheet (babqua.css), and the Quarto metadata (_extension.yml) all live here.
  • docs/ — this Quarto book. Each chapter is a .qmd file; the filter renders the live {.clojure .bb} blocks against the in-tree extension.
  • docs/_extensions/bb/ — symlink shim pointing back to _extensions/bb/. Quarto requires an _extensions/ directory adjacent to the _quarto.yml it’s rendering, so the docs book needs its own copy of the extension. The symlinks let the docs pick up changes to the in-tree extension immediately, without going through quarto add. If you add a new file to _extensions/bb/, mirror it as a symlink in docs/_extensions/bb/.

The published install path is _extensions/scicloj/bb/ (created by quarto add scicloj/babqua); the in-tree _extensions/bb/ is what this repo ships. The docs book uses the symlink shim above to render against the in-tree copy, matching Janqua’s setup.

For an end-to-end walk through a single render — what each pass does, how the bb runtime is invoked, how chart payloads reach the browser — see How It Works.

7.2 Local setup

git clone https://github.com/scicloj/babqua
cd babqua/docs
quarto render

The symlinks are committed, so there’s no setup script. A clean render produces docs/_book/ with one HTML file per chapter.

For live iteration as you edit:

cd docs && quarto preview

Quarto serves the book at a local URL and re-renders each chapter you save. For chapters with heavy bb.edn deps or pods, the optional persistent bb session described in Workflow keeps state warm across saves.

Or render a single chapter directly for the fastest one-shot feedback:

cd docs && quarto render demo.qmd

demo.qmd exercises every Kindly kind plus stdout, errors, and a live HTTP fetch in a single file.

7.3 Releases

Tags are cut from main. The version-bump goes in its own commit, separate from any pre-release fixes.