0
# Cell Interfaces
1

2
Comprehensive type definitions for all notebook cell types including code, markdown, and raw cells, with their associated metadata structures and type guard functions.
3

4
## Capabilities
5

6
### Cell Union Type and Base Interface
7

8
Core cell type definitions and the base interface all cells extend.
9

10
```typescript { .api }
11
/**
12
 * A cell union type representing all possible cell types
13
 */
14
type ICell = IRawCell | IMarkdownCell | ICodeCell | IUnrecognizedCell;
15

16
/**
17
 * A type describing the type of cell
18
 */
19
type CellType = 'code' | 'markdown' | 'raw' | string;
20

21
/**
22
 * The base cell interface that all cells extend
23
 */
24
interface IBaseCell extends PartialJSONObject {
25
  /** String identifying the type of cell */
26
  cell_type: string;
27
  /** Contents of the cell, represented as an array of lines or single string */
28
  source: MultilineString;
29
  /** Cell-level metadata */
30
  metadata: Partial<ICellMetadata>;
31
}
32
```
33

34
### Cell Metadata Interfaces
35

36
Metadata structures for different cell types.
37

38
```typescript { .api }
39
/**
40
 * Union metadata type for all cell types
41
 */
42
type ICellMetadata = IBaseCellMetadata | IRawCellMetadata | ICodeCellMetadata;
43

44
/**
45
 * Cell-level metadata base interface
46
 */
47
interface IBaseCellMetadata extends PartialJSONObject {
48
  /** Whether the cell is trusted (security-related) */
49
  trusted: boolean;
50
  /** The cell's name. If present, must be a non-empty string */
51
  name: string;
52
  /** The Jupyter metadata namespace */
53
  jupyter: Partial<IBaseCellJupyterMetadata>;
54
  /** The cell's tags. Tags must be unique, and must not contain commas */
55
  tags: string[];
56
}
57

58
/**
59
 * The Jupyter metadata namespace for cells
60
 */
61
interface IBaseCellJupyterMetadata extends PartialJSONObject {
62
  /** Whether the source is hidden */
63
  source_hidden: boolean;
64
}
65
```
66

67
### Code Cell Interface
68

69
Interface for executable code cells with outputs and execution tracking.
70

71
```typescript { .api }
72
/**
73
 * A code cell interface for executable code
74
 */
75
interface ICodeCell extends IBaseCell {
76
  /** Cell identifier (optional in nbformat 4.4, required in 4.5+) */
77
  id?: string;
78
  /** String identifying the type of cell */
79
  cell_type: 'code';
80
  /** Cell-level metadata */
81
  metadata: Partial<ICodeCellMetadata>;
82
  /** Execution, display, or stream outputs */
83
  outputs: IOutput[];
84
  /** The code cell's prompt number. Will be null if the cell has not been run */
85
  execution_count: ExecutionCount;
86
}
87

88
/**
89
 * Metadata for a code cell
90
 */
91
interface ICodeCellMetadata extends IBaseCellMetadata {
92
  /** Whether the cell is collapsed/expanded */
93
  collapsed: boolean;
94
  /** The Jupyter metadata namespace */
95
  jupyter: Partial<ICodeCellJupyterMetadata>;
96
  /** Whether the cell's output is scrolled, unscrolled, or autoscrolled */
97
  scrolled: boolean | 'auto';
98
}
99

100
/**
101
 * The Jupyter metadata namespace for code cells
102
 */
103
interface ICodeCellJupyterMetadata extends IBaseCellJupyterMetadata {
104
  /** Whether the outputs are hidden */
105
  outputs_hidden: boolean;
106
}
107
```
108

109
**Usage Example:**
110

111
```typescript
112
import { ICodeCell, ExecutionCount } from "@jupyterlab/nbformat";
113

114
const codeCell: ICodeCell = {
115
  cell_type: 'code',
116
  source: ['print("Hello, world!")', 'x = 42'],
117
  metadata: {
118
    trusted: true,
119
    name: "hello_world",
120
    jupyter: {
121
      source_hidden: false,
122
      outputs_hidden: false
123
    },
124
    tags: ["example"],
125
    collapsed: false,
126
    scrolled: false
127
  },
128
  outputs: [],
129
  execution_count: null
130
};
131
```
132

133
### Markdown Cell Interface
134

135
Interface for markdown documentation cells.
136

137
```typescript { .api }
138
/**
139
 * A markdown cell interface for documentation
140
 */
141
interface IMarkdownCell extends IBaseCell {
142
  /** Cell identifier (optional in nbformat 4.4, required in 4.5+) */
143
  id?: string;
144
  /** String identifying the type of cell */
145
  cell_type: 'markdown';
146
  /** Cell attachments (e.g., inline images) */
147
  attachments?: IAttachments;
148
}
149
```
150

151
**Usage Example:**
152

153
```typescript
154
import { IMarkdownCell } from "@jupyterlab/nbformat";
155

156
const markdownCell: IMarkdownCell = {
157
  cell_type: 'markdown',
158
  source: ['# Title', '', 'Some **bold** text.'],
159
  metadata: {
160
    trusted: true,
161
    name: "title_cell",
162
    jupyter: {
163
      source_hidden: false
164
    },
165
    tags: ["documentation"]
166
  }
167
};
168
```
169

170
### Raw Cell Interface
171

172
Interface for raw text cells that bypass processing.
173

174
```typescript { .api }
175
/**
176
 * A raw cell interface for unprocessed text
177
 */
178
interface IRawCell extends IBaseCell {
179
  /** Cell identifier (optional in nbformat 4.4, required in 4.5+) */
180
  id?: string;
181
  /** String identifying the type of cell */
182
  cell_type: 'raw';
183
  /** Cell-level metadata */
184
  metadata: Partial<IRawCellMetadata>;
185
  /** Cell attachments */
186
  attachments?: IAttachments;
187
}
188

189
/**
190
 * Metadata for the raw cell
191
 */
192
interface IRawCellMetadata extends IBaseCellMetadata {
193
  /** Raw cell metadata format for nbconvert */
194
  format: string;
195
}
196
```
197

198
### Unrecognized Cell Interface
199

200
Interface for cells that don't match known types.
201

202
```typescript { .api }
203
/**
204
 * An unrecognized cell interface for unknown cell types
205
 */
206
interface IUnrecognizedCell extends IBaseCell {}
207
```
208

209
### Cell Type Guard Functions
210

211
Runtime type checking functions to determine cell types.
212

213
```typescript { .api }
214
/**
215
 * Test whether a cell is a raw cell
216
 */
217
function isRaw(cell: ICell): cell is IRawCell;
218

219
/**
220
 * Test whether a cell is a markdown cell  
221
 */
222
function isMarkdown(cell: ICell): cell is IMarkdownCell;
223

224
/**
225
 * Test whether a cell is a code cell
226
 */
227
function isCode(cell: ICell): cell is ICodeCell;
228
```
229

230
**Usage Example:**
231

232
```typescript
233
import { ICell, isCode, isMarkdown, isRaw } from "@jupyterlab/nbformat";
234

235
function processCells(cells: ICell[]): void {
236
  cells.forEach((cell, index) => {
237
    if (isCode(cell)) {
238
      console.log(`Cell ${index}: Code cell with ${cell.outputs.length} outputs`);
239
      console.log(`Execution count: ${cell.execution_count}`);
240
    } else if (isMarkdown(cell)) {
241
      console.log(`Cell ${index}: Markdown cell`);
242
    } else if (isRaw(cell)) {
243
      console.log(`Cell ${index}: Raw cell with format: ${cell.metadata.format || 'none'}`);
244
    } else {
245
      console.log(`Cell ${index}: Unrecognized cell type: ${cell.cell_type}`);
246
    }
247
  });
248
}
249
```
250

251
## Types
252

253
```typescript { .api }
254
/**
255
 * The code cell's prompt number. Will be null if the cell has not been run
256
 */
257
type ExecutionCount = number | null;
258

259
/**
260
 * A multiline string that can be a single string or array of strings
261
 */
262
type MultilineString = string | string[];
263

264
/**
265
 * Media attachments (e.g. inline images)
266
 */
267
interface IAttachments {
268
  [key: string]: IMimeBundle | undefined;
269
}
270
```