Skip to content

Commit f3dd8ba

Browse files
mbostockmbostock
committed
more kit docs
1 parent fe5ddc3 commit f3dd8ba

File tree

2 files changed

+175
-3
lines changed

2 files changed

+175
-3
lines changed

‎docs/kit.html

Lines changed: 174 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
**Observable Notebook Kit** is an [open-source command-line tool](https://github.com/observablehq/notebook-kit) for building static sites from Observable Notebooks based on an open file format. Notebook Kit also includes a Vite plugin and a low-level JavaScript interface for deep integration of Observable Notebooks with custom web applications.
1111
</script>
1212
<script id="43" type="text/markdown">
13-
Notebook Kit is available as part of [**Notebooks 2.0 Technology Preview**](./), which includes **Observable Desktop**, a notebook editor for macOS.
13+
Notebook Kit is available as part of [**Notebooks 2.0 Technology Preview**](./), which includes **Observable Desktop**, a macOS application for editing notebooks.
1414
</script>
1515
<script id="46" type="text/markdown">
1616
For more on authoring notebooks, see the [Notebooks system guide](./system-guide).
@@ -28,6 +28,178 @@
2828

2929
Notebook Kit requires [Node.js](https://nodejs.org/en) 20.19+ or 22.12+.
3030
</script>
31+
<script id="47" type="text/markdown">
32+
---
33+
34+
## The notebook file format
35+
36+
The notebook file format is intended to be simple, human-readable, and human-editable. It's based on HTML, which means you get nice editing affordances in today's text editors without needing special plugins. In addition, it's easy to review diffs when storing notebooks in source control, to search, to find-and-replace, and countless other workflows.
37+
</script>
38+
<script id="48" type="text/markdown">
39+
<aside>While you can edit notebook HTML directly, we recommend installing <a href="./desktop">Observable Desktop</a> to author notebooks.</aside>
40+
41+
A notebook HTML file consists of:
42+
43+
- a <code class="language-html">&lt;notebook&gt;</code> root element,
44+
- an optional <code class="language-html">&lt;title&gt;</code> element, and
45+
- one <code class="language-html">&lt;script&gt;</code> element per cell.
46+
</script>
47+
<script id="50" type="text/markdown">
48+
Here's a simple "hello world" notebook to demonstrate:
49+
50+
```html
51+
<!doctype html>
52+
<notebook>
53+
<title>Hello, world!</title>
54+
<script id="1" type="text/markdown">
55+
# Hello, world!
56+
<\/script>
57+
<script id="2" type="module" pinned>
58+
1 + 2
59+
<\/script>
60+
</notebook>
61+
```
62+
</script>
63+
<script id="60" type="text/markdown">
64+
The cell <code class="language-html">&lt;script&gt;</code> element should use four spaces of indentation for each line; these four leading spaces will be trimmed when parsing the notebook. (In the future, we'll likely make this contextual to allow more or less indentation.)
65+
</script>
66+
<script id="49" type="text/markdown">
67+
The `type` attribute determines each cell's mode, which can be one of:
68+
69+
- `module` - JavaScript
70+
- `text/markdown` - Markdown
71+
- `text/html` - HTML
72+
- `application/sql` - SQL
73+
- `application/x-tex` - ${tex`\TeX`}
74+
- `text/vnd.graphviz` - DOT (Graphviz)
75+
- `application/vnd.observable.javascript` - Observable JavaScript
76+
77+
Here's an example of each supported cell type.
78+
</script>
79+
<script id="59" type="text/markdown">
80+
A JavaScript (`module`) cell:
81+
82+
```html
83+
<script type="module">
84+
1 + 2
85+
<\/script>
86+
```
87+
</script>
88+
<script id="52" type="text/markdown">
89+
A Markdown (`text/markdown`) cell:
90+
91+
```html
92+
<script type="text/markdown">
93+
# Hello, world!
94+
<\/script>
95+
```
96+
</script>
97+
<script id="61" type="text/markdown">
98+
An HTML (`text/html`) cell:
99+
100+
```html
101+
<script type="text/html">
102+
<h1>Hello, <i>world</i>!</h1>
103+
<\/script>
104+
```
105+
</script>
106+
<script id="62" type="text/markdown">
107+
A SQL (`application/sql`) cell:
108+
109+
```html
110+
<script type="application/sql">
111+
SELECT * FROM customers
112+
<\/script>
113+
```
114+
</script>
115+
<script id="63" type="text/markdown">
116+
A ${tex`\TeX`} (`application/x-tex`) cell:
117+
118+
```html
119+
<script type="application/x-tex">
120+
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
121+
<\/script>
122+
```
123+
</script>
124+
<script id="65" type="text/markdown">
125+
A DOT (`text/vnd.graphviz`) cell:
126+
127+
```html
128+
<script type="text/vnd.graphviz">
129+
digraph G {
130+
A -> B -> C;
131+
A -> C;
132+
}
133+
<\/script>
134+
```
135+
</script>
136+
<script id="66" type="text/markdown">
137+
An Observable JavaScript (`application/vnd.observable.javascript`) cell:
138+
139+
```html
140+
<script type="application/vnd.observable.javascript">
141+
foo = 42
142+
<\/script>
143+
```
144+
</script>
145+
<script id="51" type="text/markdown">
146+
The `pinned` attribute determines whether to show the cell's source code; it defaults to true for JavaScript cells, and false for all other cells. Cells can also have an `id` attribute to indicate a unique (positive integer) identifier; an `id` isn't required, but gives cells a stable identity for editing.
147+
</script>
148+
<script id="53" type="text/markdown">
149+
Since each cell is specified as a <code class="language-html">&lt;script&gt;</code> element, if the cell source code contains a `<\/script>`, it must be escaped with a backslash as `<\\/script>`. Likewise, a sequence of backslashes in this context must be escaped with an additional backslash, such as `<\\\/script>`.
150+
</script>
151+
<script id="57" type="text/markdown">
152+
The `notebook` element `theme` attribute specifies the theme; and may have one of the following values:
153+
154+
- `air` (default)
155+
- `coffee`
156+
- `cotton`
157+
- `deep-space`
158+
- `glacier`
159+
- `ink`
160+
- `midnight`
161+
- `near-midnight`
162+
- `ocean-floor`
163+
- `parchment`
164+
- `slate`
165+
- `stark`
166+
- `sun-faded`
167+
168+
See [Observable Framework's themes](https://observablehq.com/framework/themes) for a visual overview of themes. More themes may be added in the future, and custom themes can be designed using standard stylesheets.
169+
</script>
170+
<script id="56" type="text/markdown">
171+
See [`notebook.ts`](https://github.com/observablehq/notebook-kit/blob/main/src/lib/notebook.ts) for TypeScript types representing notebooks and cells.
172+
</script>
173+
<script id="70" type="text/markdown">
174+
---
175+
176+
## The page template format
177+
178+
Notebook Kit supports custom page templates when previewing and building notebooks. Page templates can provide additional chrome around the notebook, such as a header and footer. A page template HTML file can contain whatever you like. Notebook Kit will insert or modify the following elements:
179+
180+
- <code class="language-html">&lt;meta name=\"generator\"&gt;</code> - Notebook Kit version and attribution
181+
- <code class="language-html">&lt;title&gt;</code> - a title suffix, appearing after the notebook title
182+
- <code class="language-html">&lt;main&gt;</code> - where to render the notebook cells
183+
</script>
184+
<script id="69" type="text/markdown">
185+
The [default template](https://github.com/observablehq/notebook-kit/blob/main/src/templates/default.html) looks something like this:
186+
187+
```html
188+
<!doctype html>
189+
<html lang="en">
190+
<head>
191+
<meta charset="utf-8">
192+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
193+
<style type="text/css">
194+
@import url("observable:styles/index.css");
195+
</style>
196+
</head>
197+
<body>
198+
<main></main>
199+
</body>
200+
</html>
201+
```
202+
</script>
31203
<script id="8" type="text/markdown">
32204
---
33205

@@ -172,7 +344,7 @@
172344
Clears a cell's output (from the `root` given by the specified `state`). (This method is used internally to clear the display when a cell is invalidated.)
173345
</script>
174346
<script id="31" type="text/markdown">
175-
#### <code class="language-ts">observe(state: DisplayState, id: number, autodisplay?: boolean): void</code>
347+
#### <code class="language-ts">observe(state: DisplayState, definition: Definition): void</code>
176348

177349
Returns the default [variable observer](https://github.com/observablehq/runtime/blob/main/README.md#modulevariableobserver) used to render the cell's contents.
178350
</script>

‎src/vite/observable.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ export function observable({
5555
let generator = document.querySelector("meta[name=generator]");
5656
generator ??= document.head.appendChild(document.createElement("meta"));
5757
generator.setAttribute("name", "generator");
58-
generator.setAttribute("content", `Observable Notebooks v${version}`);
58+
generator.setAttribute("content", `Observable Notebook Kit v${version}`);
5959

6060
let title = document.querySelector("title");
6161
title ??= document.head.appendChild(document.createElement("title"));

0 commit comments

Comments
 (0)