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 (:clay key)
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 &quot;$FilePath$&quot;}))"
         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

clay

同仓库更多 Skills

同仓库更多 Skills

Clay

Overview

Installation

Core Concepts

Kindly Convention

make! Function

Output Formats

API Reference

Core Functions

make!

browse!

Configuration

Visualization Kinds

Markup

kind/md - Markdown

kind/hiccup - HTML

kind/html - Raw HTML

kind/code - Code Display

kind/tex - LaTeX

Data Visualization

kind/vega-lite - Vega-Lite Charts

kind/plotly - Plotly Charts

kind/echarts - Apache ECharts

kind/highcharts - Highcharts

Tabular Data

kind/table - Tables

kind/dataset - tech.ml.dataset

Media

kind/image - Images

kind/video - Video

Interactive Components

kind/reagent - Reagent Components

Structure

kind/fragment - Multiple Items

kind/hidden - Hide Output

Diagrams

kind/mermaid - Flowcharts

kind/cytoscape - Network Graphs

Common Patterns

Basic Notebook Structure

Hide Code

Styling

Quarto Integration

Multi-File Projects

File Watching

Editor Integration

Calva (VSCode)

CIDER (Emacs)

Cursive (IntelliJ)

Conjure (Neovim)

Performance Considerations

Delays for Expensive Computations

Large Datasets

Subdirectory Syncing

Error Handling

Missing Dependencies

Kind Not Rendering

Platform Notes

Resources

License

Clay

Overview

Installation

Core Concepts

Kindly Convention

make! Function

Output Formats

API Reference

Core Functions

make!

browse!

Configuration

Visualization Kinds

Markup

kind/md - Markdown

kind/hiccup - HTML

kind/html - Raw HTML