hugoduncan Clay
REPL-friendly Clojure tool for data visualization and literate programming. Renders Clojure namespaces and forms as HTML pages, notebooks, and Quarto documents using the Kindly convention.
Overview
Clay transforms Clojure code into visual documents by interpreting the Kindly convention for data visualization. It integrates with your REPL workflow and editor, rendering forms and namespaces as HTML with support for charts, tables, markdown, and interactive components.
Key Features:
- REPL-driven visualization workflow
- Kindly convention for visualization types
- HTML, Quarto markdown, and reveal.js output
- Live reload with file watching
- Editor integrations (Calva, CIDER, Cursive, Conjure)
- Vega-Lite, Plotly, ECharts, Highcharts support
- Dataset and table rendering
- Reagent component support
Artifact: org.scicloj/clay
Latest Version: 2.0.3
License: EPL-1.0
Repository: https://github.com/scicloj/clay
Installation
Add to deps.edn:
{:deps {org.scicloj/clay {:mvn/version "2.0.3"}}}
Or Leiningen project.clj:
[org.scicloj/clay "2.0.3"]
Import in namespace:
(ns my-notebook
(:require [scicloj.clay.v2.api :as clay]
[scicloj.kindly.v4.kind :as kind]))
Core Concepts
Kindly Convention
Kindly standardizes how values request visualization. Attach kind metadata to values:
;; Using kind function
(kind/md "# Hello World")
;; Using metadata
^:kind/md ["# Hello World"]
make! Function
The primary entry point. Renders forms, namespaces, or files:
;; Render single form
(clay/make! {:single-form '(+ 1 2 3)})
;; Render current namespace
(clay/make! {:source-path "notebooks/my_notebook.clj"})
;; Render with options
(clay/make! {:source-path "src/analysis.clj"
:format [:html]
:show true})
Output Formats
Clay produces:
- HTML - Standalone pages served at
http://localhost:1971/ - Quarto Markdown - For publishing with Quarto
- reveal.js - Slideshows
API Reference
Core Functions
make!
Render content with configuration options.
(clay/make! {:source-path "notebooks/analysis.clj"})
(clay/make! {:single-form '(kind/md "# Title")
:show true})
(clay/make! {:source-path "src/report.clj"
:format [:quarto :html]
:base-target-path "docs"})
Options:
:source-path- Path to .clj file to render:single-form- Single form to evaluate and render:format- Output format(s)::html,:quarto,:revealjs:show- Open browser after rendering (default: true):browse- Enable browser opening:title- Document title:favicon- Path to favicon:base-target-path- Output directory (default: "docs"):quarto- Quarto-specific configuration map
browse!
Reopen the Clay view in browser.
(clay/browse!)
Configuration
Configuration merges from multiple sources (lowest to highest priority):
- Default settings (
clay-default.edn) - User config (
~/.config/scicloj-clay/config.edn) - Project config (
clay.edn) - Namespace metadata (
:claykey) - Function call arguments
Project clay.edn:
{:source-path "notebooks"
:base-target-path "docs"
:show true
:format [:html]
:quarto {:format {:html {:theme :cosmo}}}}
Namespace metadata:
(ns my-notebook
{:clay {:title "My Analysis"
:quarto {:format {:html {:toc true}}}}})
Visualization Kinds
Markup
kind/md - Markdown
(kind/md "# Heading
Paragraph with **bold** and *italic*.
- List item 1
- List item 2")
;; With LaTeX
(kind/md "Let $x=9$. Then $x^2=81$.")
kind/hiccup - HTML
(kind/hiccup
[:div {:style {:color "blue"}}
[:h1 "Title"]
[:p "Paragraph"]
[:ul
[:li "Item 1"]
[:li "Item 2"]]])
kind/html - Raw HTML
(kind/html "<div class='alert'>Warning!</div>")
kind/code - Code Display
(kind/code "(defn hello [name]
(str \"Hello, \" name \"!\"))")
kind/tex - LaTeX
(kind/tex "\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}")
Data Visualization
kind/vega-lite - Vega-Lite Charts
(kind/vega-lite
{:data {:values [{:x 1 :y 2}
{:x 2 :y 4}
{:x 3 :y 3}]}
:mark :line
:encoding {:x {:field :x :type :quantitative}
:y {:field :y :type :quantitative}}})
;; Bar chart
(kind/vega-lite
{:data {:values [{:category "A" :value 28}
{:category "B" :value 55}
{:category "C" :value 43}]}
:mark :bar
:encoding {:x {:field :category :type :nominal}
:y {:field :value :type :quantitative}}})
kind/plotly - Plotly Charts
(kind/plotly
{:data [{:x [1 2 3 4]
:y [10 15 13 17]
:type :scatter
:mode :lines+markers}]
:layout {:title "Line Chart"}})
;; 3D scatter
(kind/plotly
{:data [{:x [1 2 3]
:y [1 2 3]
:z [1 2 3]
:type :scatter3d
:mode :markers}]})
kind/echarts - Apache ECharts
(kind/echarts
{:xAxis {:type :category
:data ["Mon" "Tue" "Wed" "Thu" "Fri"]}
:yAxis {:type :value}
:series [{:data [150 230 224 218 135]
:type :bar}]})
kind/highcharts - Highcharts
(kind/highcharts
{:chart {:type :line}
:title {:text "Monthly Sales"}
:xAxis {:categories ["Jan" "Feb" "Mar" "Apr"]}
:series [{:name "Sales"
:data [29.9 71.5 106.4 129.2]}]})
Tabular Data
kind/table - Tables
;; Row vectors
(kind/table
{:column-names [:name :age :city]
:row-vectors [["Alice" 30 "NYC"]
["Bob" 25 "LA"]
["Carol" 35 "Chicago"]]})
;; Row maps
(kind/table
{:row-maps [{:name "Alice" :age 30}
{:name "Bob" :age 25}]})
;; With DataTables options
(kind/table
{:row-maps data
:use-datatables true})
kind/dataset - tech.ml.dataset
(require '[tablecloth.api :as tc])
(-> (tc/dataset {:x [1 2 3]
:y [4 5 6]})
kind/dataset)
;; With print options
(-> dataset
(kind/dataset {:dataset/print-range 20}))
Media
kind/image - Images
;; From URL
(kind/image {:src "https://example.com/image.png"})
;; BufferedImage object
(kind/image buffered-image)
;; With caption
(kind/image {:src "chart.png"
:alt "Sales Chart"})
kind/video - Video
;; URL
(kind/video {:src "video.mp4"})
;; YouTube
(kind/video {:youtube-id "dQw4w9WgXcQ"})
Interactive Components
kind/reagent - Reagent Components
(kind/reagent
['(fn []
(let [count (reagent.core/atom 0)]
(fn []
[:div
[:p "Count: " @count]
[:button {:on-click #(swap! count inc)}
"Increment"]])))])
;; With dependencies
(kind/reagent
['(fn [] [:div "Component"])]
{:deps [:reagent]})
Structure
kind/fragment - Multiple Items
(kind/fragment
[(kind/md "# Section 1")
(kind/vega-lite chart-spec)
(kind/md "## Analysis")
(kind/table data)])
kind/hidden - Hide Output
(kind/hidden (expensive-computation))
Diagrams
kind/mermaid - Flowcharts
(kind/mermaid
"graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Do Something]
B -->|No| D[Do Other]")
kind/cytoscape - Network Graphs
(kind/cytoscape
{:elements {:nodes [{:data {:id "a"}}
{:data {:id "b"}}]
:edges [{:data {:source "a" :target "b"}}]}
:style [{:selector "node"
:style {:label "data(id)"}}]
:layout {:name "preset"}})
Common Patterns
Basic Notebook Structure
(ns my-notebook
{:clay {:title "Data Analysis"}}
(:require [scicloj.kindly.v4.kind :as kind]
[tablecloth.api :as tc]))
;; # Introduction
;; This notebook analyzes...
^:kindly/hide-code
(def data (tc/dataset {:x (range 10)
:y (map #(* % %) (range 10))}))
;; ## Data Overview
(kind/table {:row-maps (tc/rows data :as-maps)})
;; ## Visualization
(kind/vega-lite
{:data {:values (tc/rows data :as-maps)}
:mark :point
:encoding {:x {:field :x :type :quantitative}
:y {:field :y :type :quantitative}}})
Hide Code
;; Hide code for specific form
^:kindly/hide-code
(kind/md "Only output visible")
;; Global hide for certain kinds
{:kindly/options {:kinds-that-hide-code #{:kind/md :kind/hiccup}}}
Styling
;; CSS via kindly options
(-> (kind/hiccup [:div "Styled"])
(kind/hiccup {:element/style {:color "red"
:font-size "20px"}}))
;; CSS classes
(kind/hiccup
[:div {:class "alert alert-warning"}
"Warning message"])
Quarto Integration
(ns my-doc
{:clay {:quarto {:format {:html {:toc true
:theme :cosmo}}
:title "My Document"
:author "Name"}}})
;; Generate Quarto output
(clay/make! {:source-path "notebooks/doc.clj"
:format [:quarto]})
Multi-File Projects
;; Render multiple files
(clay/make! {:source-path ["src/intro.clj"
"src/analysis.clj"
"src/conclusion.clj"]
:base-target-path "docs"})
File Watching
;; Watch for changes
(clay/make! {:source-path "notebooks"
:watch true})
Editor Integration
Calva (VSCode)
Use Calva Power Tools or add to .clojure/calva.exports/config.edn:
{:customREPLCommandSnippets
[{:name "Clay: Make HTML"
:snippet "(do (require '[scicloj.clay.v2.api :as clay])
(clay/make! {:source-path \"$current-file-name\"
:format [:html]}))"}]}
CIDER (Emacs)
Install clay.el package or add manually:
(defun clay-make ()
(interactive)
(cider-interactive-eval
(format "(do (require '[scicloj.clay.v2.api :as clay])
(clay/make! {:source-path \"%s\"}))"
(buffer-file-name))))
Cursive (IntelliJ)
Add to .idea/repl-commands.xml:
<command command="(do (require '[scicloj.clay.v2.api :as clay])
(clay/make! {:source-path "$FilePath$"}))"
name="Clay: Make HTML"/>
Conjure (Neovim)
Install clay.nvim plugin.
Performance Considerations
Delays for Expensive Computations
;; Computation runs only when visualized
(delay
(Thread/sleep 5000)
(kind/md "Slow result"))
Large Datasets
;; Limit displayed rows
(-> large-dataset
(kind/dataset {:dataset/print-range 100}))
Subdirectory Syncing
;; Only sync specified directories (excludes src)
{:subdirs-to-sync ["notebooks" "data"]}
Error Handling
Missing Dependencies
Ensure visualization libraries are loaded:
;; For datasets
{:deps {scicloj/tablecloth {:mvn/version "..."}}}
;; For specific chart types
{:deps {applied-science/darkstar {:mvn/version "..."}}}
Kind Not Rendering
Verify kind is attached correctly:
;; Check metadata
(meta (kind/md "test"))
;;=> {:kindly/kind :kind/md}
Platform Notes
JVM Only: Clay requires the JVM and is not compatible with Babashka or ClojureScript compilation. It renders ClojureScript components (Reagent) but runs on the JVM.
Browser Required: Visualization output is served via local HTTP server and displayed in browser.
Resources
- Documentation: https://scicloj.github.io/clay/
- GitHub: https://github.com/scicloj/clay
- Kindly Spec: https://scicloj.github.io/kindly-noted/
- Zulip: Clojurians #clay-dev channel
License
Copyright © Scicloj Distributed under the EPL-1.0 (same as Clojure)