0
# Notebook Support
1

2
Notebook document synchronization and management for Jupyter notebooks and other notebook formats. Supports both notebook-level and cell-level text document management with comprehensive lifecycle tracking.
3

4
## Capabilities
5

6
### Notebook Documents Manager
7

8
A manager for notebook documents that handles both notebook-level events and individual cell text documents.
9

10
```typescript { .api }
11
/**
12
 * A manager for notebook documents that tracks both notebooks and their cell text documents
13
 */
14
class NotebookDocuments<T extends { uri: DocumentUri }> {
15
    /**
16
     * Create a new notebook documents manager
17
     * @param configurationOrTextDocuments Either a text documents configuration or an existing TextDocuments instance
18
     */
19
    constructor(configurationOrTextDocuments: TextDocumentsConfiguration<T> | TextDocuments<T>);
20
    
21
    /** Event fired when a notebook document has been opened */
22
    readonly onDidOpen: Event<NotebookDocument>;
23
    
24
    /** Event fired when a notebook document has changed */
25
    readonly onDidChange: Event<NotebookDocumentChangeEvent>;
26
    
27
    /** Event fired when a notebook document has been saved */
28
    readonly onDidSave: Event<NotebookDocument>;
29
    
30
    /** Event fired when a notebook document has been closed */
31
    readonly onDidClose: Event<NotebookDocument>;
32
    
33
    /**
34
     * Returns the text document for the given cell URI
35
     * @param cellUri The URI of the notebook cell
36
     */
37
    getCellTextDocument(cellUri: DocumentUri): T | undefined;
38
    
39
    /**
40
     * Returns the notebook document for the given notebook URI
41
     * @param notebookUri The URI of the notebook document
42
     */
43
    getNotebookDocument(notebookUri: DocumentUri): NotebookDocument | undefined;
44
    
45
    /**
46
     * Returns the notebook cell for the given cell URI
47
     * @param cellUri The URI of the notebook cell
48
     */
49
    getNotebookCell(cellUri: DocumentUri): NotebookCell | undefined;
50
    
51
    /**
52
     * Listens for notebook synchronization notifications and cell text document changes
53
     * @param connection The connection to listen on
54
     */
55
    listen(connection: Connection): void;
56
}
57
```
58

59
**Usage Example:**
60

61
```typescript
62
import { NotebookDocuments, createConnection } from "vscode-languageserver";
63
import { TextDocument } from "vscode-languageserver-textdocument";
64

65
// Create connection and notebook documents manager
66
const connection = createConnection();
67
const notebooks = new NotebookDocuments(TextDocument);
68

69
// Listen for notebook events
70
notebooks.onDidOpen(notebook => {
71
    console.log(`Notebook opened: ${notebook.uri}`);
72
    console.log(`Cells: ${notebook.cells.length}`);
73
});
74

75
notebooks.onDidChange(event => {
76
    console.log(`Notebook changed: ${event.notebook.uri}`);
77
    event.contentChanges.forEach(change => {
78
        console.log(`Changed cells: ${change.cells?.length || 0}`);
79
    });
80
});
81

82
notebooks.onDidSave(notebook => {
83
    console.log(`Notebook saved: ${notebook.uri}`);
84
});
85

86
notebooks.onDidClose(notebook => {
87
    console.log(`Notebook closed: ${notebook.uri}`);
88
});
89

90
// Connect notebooks to the connection
91
notebooks.listen(connection);
92

93
// Access notebook and cell documents
94
const notebook = notebooks.getNotebookDocument("file:///path/to/notebook.ipynb");
95
const cell = notebooks.getNotebookCell("vscode-notebook-cell:/path/to/notebook.ipynb#cell1");
96
const cellDocument = notebooks.getCellTextDocument("vscode-notebook-cell:/path/to/notebook.ipynb#cell1");
97
```
98

99
### Notebook Synchronization Feature
100

101
Feature interface for handling notebook synchronization events directly through the connection.
102

103
```typescript { .api }
104
/**
105
 * Notebook synchronization feature for handling notebook lifecycle events
106
 */
107
interface NotebookSyncFeatureShape {
108
    synchronization: {
109
        /** Register handler for notebook open notifications */
110
        onDidOpenNotebookDocument(handler: NotificationHandler1<DidOpenNotebookDocumentParams>): Disposable;
111
        /** Register handler for notebook change notifications */
112
        onDidChangeNotebookDocument(handler: NotificationHandler1<DidChangeNotebookDocumentParams>): Disposable;
113
        /** Register handler for notebook save notifications */
114
        onDidSaveNotebookDocument(handler: NotificationHandler1<DidSaveNotebookDocumentParams>): Disposable;
115
        /** Register handler for notebook close notifications */
116
        onDidCloseNotebookDocument(handler: NotificationHandler1<DidCloseNotebookDocumentParams>): Disposable;
117
    };
118
}
119
```
120

121
**Direct Usage Example:**
122

123
```typescript
124
// Access via connection.notebooks.synchronization
125
connection.notebooks.synchronization.onDidOpenNotebookDocument(params => {
126
    console.log(`Notebook opened: ${params.notebookDocument.uri}`);
127
    params.cellTextDocuments.forEach(cell => {
128
        console.log(`Cell: ${cell.uri} (${cell.languageId})`);
129
    });
130
});
131

132
connection.notebooks.synchronization.onDidChangeNotebookDocument(params => {
133
    console.log(`Notebook changed: ${params.notebookDocument.uri}`);
134
    params.change.cells?.structure?.array?.forEach(change => {
135
        console.log(`Cell operation: ${change.start} +${change.deleteCount} ${change.cells?.length || 0}`);
136
    });
137
});
138
```
139

140
### Notebook Document Structure
141

142
Core interfaces for notebook documents and cells.
143

144
```typescript { .api }
145
/**
146
 * A notebook document represents a collection of cells
147
 */
148
interface NotebookDocument {
149
    /** The notebook document's URI */
150
    uri: DocumentUri;
151
    /** The type of the notebook */
152
    notebookType: string;
153
    /** The version number of this document */
154
    version: number;
155
    /** Additional metadata stored with the notebook */
156
    metadata?: LSPObject;
157
    /** The cells of a notebook */
158
    cells: NotebookCell[];
159
}
160

161
/**
162
 * A notebook cell represents a single cell in a notebook
163
 */
164
interface NotebookCell {
165
    /** The cell's kind */
166
    kind: NotebookCellKind;
167
    /** The URI of the cell's text document content */
168
    document: DocumentUri;
169
    /** Additional metadata stored with the cell */
170
    metadata?: LSPObject;
171
    /** Additional execution summary information if supported by the client */
172
    executionSummary?: ExecutionSummary;
173
}
174

175
/**
176
 * The kind of a notebook cell
177
 */
178
enum NotebookCellKind {
179
    /** A markup cell is formatted source that is used for display */
180
    Markup = 1,
181
    /** A code cell is source code */
182
    Code = 2
183
}
184

185
/**
186
 * Execution summary for a notebook cell
187
 */
188
interface ExecutionSummary {
189
    /** A strict monotonically increasing value indicating the execution order of a cell inside a notebook */
190
    executionOrder?: number;
191
    /** Whether the execution was successful or not if known by the client */
192
    success?: boolean;
193
}
194
```
195

196
### Notebook Change Events
197

198
Detailed change information for notebook updates.
199

200
```typescript { .api }
201
/**
202
 * Parameters for notebook open notifications
203
 */
204
interface DidOpenNotebookDocumentParams {
205
    /** The notebook document that got opened */
206
    notebookDocument: NotebookDocument;
207
    /** The text documents that represent the content of a notebook cell */
208
    cellTextDocuments: TextDocumentItem[];
209
}
210

211
/**
212
 * Parameters for notebook change notifications
213
 */
214
interface DidChangeNotebookDocumentParams {
215
    /** The notebook document that did change */
216
    notebookDocument: VersionedNotebookDocumentIdentifier;
217
    /** The actual changes to the notebook document */
218
    change: NotebookDocumentChangeEvent;
219
}
220

221
/**
222
 * Parameters for notebook save notifications
223
 */
224
interface DidSaveNotebookDocumentParams {
225
    /** The notebook document that got saved */
226
    notebookDocument: NotebookDocumentIdentifier;
227
}
228

229
/**
230
 * Parameters for notebook close notifications
231
 */
232
interface DidCloseNotebookDocumentParams {
233
    /** The notebook document that got closed */
234
    notebookDocument: NotebookDocumentIdentifier;
235
    /** The text documents that represent the content of a notebook cell that got closed */
236
    cellTextDocuments: TextDocumentIdentifier[];
237
}
238

239
/**
240
 * A change event for a notebook document
241
 */
242
interface NotebookDocumentChangeEvent {
243
    /** The changed metadata if any */
244
    metadata?: LSPObject;
245
    /** Changes to cells */
246
    cells?: {
247
        /** Changes to the cell structure to add or remove cells */
248
        structure?: {
249
            /** The change to the number of cells in the document */
250
            array: NotebookCellArrayChange;
251
            /** Additional opened cell text documents */
252
            didOpen?: TextDocumentItem[];
253
            /** Additional closed cell text documents */
254
            didClose?: TextDocumentIdentifier[];
255
        };
256
        /** Changes to notebook cells */
257
        data?: NotebookCell[];
258
        /** Changes to the text content of notebook cells */
259
        textContent?: {
260
            document: VersionedTextDocumentIdentifier;
261
            changes: TextDocumentContentChangeEvent[];
262
        }[];
263
    };
264
}
265

266
/**
267
 * A change describing how to move a notebook cell array from state S to S'
268
 */
269
interface NotebookCellArrayChange {
270
    /** The start offset of the cell that changed */
271
    start: number;
272
    /** The deleted cells */
273
    deleteCount: number;
274
    /** The new cells, if any */
275
    cells?: NotebookCell[];
276
}
277
```
278

279
### Notebook Document Identifiers
280

281
Identification interfaces for notebook documents.
282

283
```typescript { .api }
284
/**
285
 * A literal to identify a notebook document in the client
286
 */
287
interface NotebookDocumentIdentifier {
288
    /** The notebook document's URI */
289
    uri: DocumentUri;
290
}
291

292
/**
293
 * A versioned notebook document identifier
294
 */
295
interface VersionedNotebookDocumentIdentifier extends NotebookDocumentIdentifier {
296
    /** The version number of this notebook document */
297
    version: number;
298
}
299
```
300

301
### Integration with Text Documents
302

303
Notebook cells are backed by text documents, allowing for seamless integration with existing text document features.
304

305
```typescript { .api }
306
// Notebook cells can be accessed as regular text documents
307
const cellDocument = notebooks.getCellTextDocument("vscode-notebook-cell:/path/to/notebook.ipynb#cell1");
308

309
// Use with existing text document features
310
connection.onHover((params) => {
311
    // Check if this is a notebook cell URI
312
    if (params.textDocument.uri.startsWith("vscode-notebook-cell:")) {
313
        const cellDocument = notebooks.getCellTextDocument(params.textDocument.uri);
314
        const cell = notebooks.getNotebookCell(params.textDocument.uri);
315
        
316
        if (cellDocument && cell) {
317
            // Provide hover information for notebook cell
318
            return {
319
                contents: `Notebook cell (${cell.kind === NotebookCellKind.Code ? 'Code' : 'Markdown'})`
320
            };
321
        }
322
    }
323
    return null;
324
});
325
```
326

327
## Core Types
328

329
```typescript { .api }
330
type DocumentUri = string;
331

332
type LSPObject = { [key: string]: any };
333

334
interface TextDocumentItem {
335
    /** The text document's URI */
336
    uri: DocumentUri;
337
    /** The text document's language identifier */
338
    languageId: string;
339
    /** The version number of this document */
340
    version: number;
341
    /** The content of the opened text document */
342
    text: string;
343
}
344

345
interface TextDocumentIdentifier {
346
    /** The text document's URI */
347
    uri: DocumentUri;
348
}
349

350
interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier {
351
    /** The version number of this document */
352
    version: number;
353
}
354

355
interface TextDocumentContentChangeEvent {
356
    /** The range of the document that changed */
357
    range?: Range;
358
    /** The optional length of the range that got replaced */
359
    rangeLength?: number;
360
    /** The new text for the provided range or the whole document */
361
    text: string;
362
}
363

364
type NotificationHandler1<P> = (params: P) => void;
365

366
type Event<T> = (listener: (e: T) => any, thisArg?: any) => Disposable;
367

368
interface Disposable {
369
    dispose(): void;
370
}
371
```