kindy Observable Notebook Kit
Observable Notebook Kit is an open-source CLI and Vite plugin for building static sites from Observable Notebooks.
File Format
Notebooks are .html files with this structure:
<!doctype html>
<notebook theme="air">
<title>My Notebook</title>
<script type="text/markdown">
# Hello
</script>
<script type="module" pinned>
1 + 2
</script>
</notebook>
<notebook> Attributes
theme- colorway:air(default),coffee,cotton,deep-space,glacier,ink,midnight,near-midnight,ocean-floor,parchment,slate,stark,sun-fadedreadonly- disallow editing
<script> (Cell) Attributes
type- cell language (required)pinned- show source codehidden- suppress displayoutput- variable name to expose (for non-JS cells)database- database name (SQL cells)format- output format (data loader cells)id- cell identifier
Cell Types (type values)
| Type | Language |
|---|---|
module |
JavaScript |
text/x-typescript |
TypeScript |
text/markdown |
Markdown |
text/html |
HTML |
application/sql |
SQL |
application/x-tex |
TeX/LaTeX |
text/vnd.graphviz |
DOT (Graphviz) |
application/vnd.node.javascript |
Node.js data loader |
text/x-python |
Python data loader |
text/x-r |
R data loader |
Use 4 spaces indentation inside <script> (auto-trimmed). Escape </script> as <\/script>.
CLI Commands
Install: npm add @observablehq/notebook-kit
Preview
notebooks preview --root docs
notebooks preview --root docs --template docs/custom.tmpl
Build
notebooks build --root docs -- docs/*.html
Output goes to .observable/dist.
Download
Convert Observable notebook URL to local HTML:
notebooks download https://observablehq.com/@d3/bar-chart > bar-chart.html
Query
Run database query manually:
notebooks query --database duckdb 'SELECT 1 + 2'
JavaScript in Notebooks
Expression vs Program Cells
Expression cell (implicit display):
1 + 2
Program cell (explicit display):
const foo = 1 + 2;
display(foo);
Key Built-ins
display(value)- render value to cell outputview(input)- display input, return value generatorFileAttachment("path")- load local files (same/sub directory only)invalidation- promise for cleanup on re-runvisibility- promise when cell visiblewidth- current page widthnow- current time
Standard Library
Inputs- Observable InputsPlot- Observable Plotd3- D3.jshtl,html,svg- Hypertext Literaltex,md- tagged template literals
Imports
import lib from "npm:package-name";
import {fn} from "jsr:@scope/package";
Reactivity
Top-level variables trigger re-runs. Promises auto-await; generators yield latest value.
const x = view(Inputs.range([0, 100]));
x ** 2 // re-runs when x changes
Interpolation
Use ${...} in Markdown/HTML cells:
The answer is ${x * 2}.
Database Connectors
See references/databases.md for full configuration.
Quick Setup
SQL cells use database attribute. Default is duckdb (in-memory).
<script type="application/sql" database="duckdb" output="results">
SELECT * FROM 'data.parquet'
</script>
Supported Databases
- DuckDB (
@duckdb/node-api) - SQLite (Node.js 24+ built-in)
- Postgres (
postgres) - Snowflake (
snowflake-sdk) - BigQuery (
@google-cloud/bigquery) - Databricks (
@databricks/sql)
Install drivers separately: npm add @duckdb/node-api
Query Results
- Auto-cached in
.observable/cache - Re-run via Play button or Shift+Enter in Desktop
- Delete cache file to refresh in Notebook Kit
Dynamic Queries
const db = DatabaseClient("duckdb");
const data = await db.sql`SELECT * FROM t WHERE x = ${value}`;
Data Loaders
Cells that run at build time via interpreter. Output cached in .observable/cache.
Formats
Text: text, json, csv, tsv, xml
Binary: arrow, parquet, blob, buffer
Image: png, jpeg, gif, webp, svg
Other: html
Node.js
<script type="application/vnd.node.javascript" format="json" output="data">
process.stdout.write(JSON.stringify({hello: "world"}));
</script>
Requires Node.js 22.12+. Sandboxed with read-only access to notebook directory.
Python
<script type="text/x-python" format="text" output="result">
print("hello", end="")
</script>
Requires Python 3.12+. Uses .venv if present.
R
<script type="text/x-r" format="json" output="data">
cat(jsonlite::toJSON(list(x = 1:3)))
</script>
Page Templates
Custom templates wrap built notebooks:
<!doctype html>
<html>
<head>
<style>@import url("observable:styles/index.css");</style>
</head>
<body>
<main></main> <!-- notebook renders here -->
</body>
</html>
Use --template path.tmpl with CLI.
Project Setup
Typical package.json:
{
"dependencies": {
"@observablehq/notebook-kit": "^"
},
"scripts": {
"docs:preview": "notebooks preview --root docs",
"docs:build": "notebooks build --root docs -- docs/*.html"
}
}
Configuration Files
.observable/databases.json- database configs (keep out of git).observable/cache/- query/data loader results.observable/dist/- built site
Recommended .gitignore:
.observable