Janqua

Jank code in Quarto documents

Overview

Janqua is a Quarto extension for writing Jank code in visual documents. Each {.clojure .jank} block in a .qmd file is evaluated by a Jank REPL 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. Rendering follows the Kindly convention, the same way Clay handles Clojure docs — so the patterns are familiar if you’re coming from Clay, and ready-to-publish if you’ve never written a notebook before.

Janqua already powers the first Jank post on Clojure Civitas — the Clojure community’s collaborative space.

Note

Janqua 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 Jank?

Jank is a dialect of Clojure hosted on C++ and an LLVM-based JIT. Its distinguishing feature is seamless interop with C and C++: Jank source can reach into C++ libraries to access and define types, functions, and templates directly — cpp/ forms in your code call into the native ecosystem without bindings or wrappers. Jank includes an nREPL server, which Janqua uses to evaluate code interactively during document rendering.

Use Janqua for…

  • Tutorials and documentation — about Jank 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 preview, which re-renders the page each time you save
  • Sharing on Clojure Civitas — Jank 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 Clojure documents in the Quarto world.

Janqua takes a different approach: rather than generating Quarto markdown from a Jank namespace, the Quarto filter evaluates {.clojure .jank} blocks embedded directly in .qmd files. It follows the Kindly convention for rendering annotations — with partial coverage at this stage — so familiar Kindly metadata patterns apply when authoring Jank documents.

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

How it works

  1. You write a .qmd file with {.clojure .jank} code blocks
  2. When Quarto renders the document, the Janqua filter intercepts these blocks
  3. Each block is sent to a Jank nREPL server for evaluation
  4. Results are inserted 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 Jank!"]
Hello from Jank!

The Jank process starts automatically on first render and stays running for fast re-evaluation. See Getting Started to try it out, or jump to the Demo to see evaluated examples.

Roadmap

Full Kindly support and Clay support for Jank are the larger goals.

  • Broader Kindly support — more visualization kinds (tables, images, etc.)
  • Easier setup — reducing the number of prerequisites and simplifying installation
  • Clay support for Jank — a namespace-as-a-notebook experience, where Jank source files render as documents without writing .qmd by hand
  • Jupyter support — a Jank kernel for Jupyter notebooks, enabling interactive Jank development in JupyterLab and other Jupyter-compatible environments

Chapters

  • Getting Started — prerequisites, installation, first document, rendering
  • Workflow — managing the Jank process, auto-start tuning, publishing
  • Kindly kinds — controlling how a value renders (HTML, charts, diagrams, math, …)
  • Authoring Jank documents — code-block attributes, per-block options, and document-level Quarto features
  • How It Works — architecture, port discovery, process management, evaluation pipeline
  • Demo — evaluated examples of all output kinds