0
# Document Nodes
1
2
Document structure elements that form the hierarchical content of markdown documents. These nodes represent block-level elements like headings, paragraphs, lists, code blocks, and media.
3
4
## Capabilities
5
6
### Document Root
7
8
The root container node that holds all document content.
9
10
```typescript { .api }
11
/**
12
* Root document container schema with content pattern 'block+'
13
* Defines the top-level document structure
14
*/
15
const docSchema: $node;
16
```
17
18
### Text Node
19
20
Basic text content within other nodes.
21
22
```typescript { .api }
23
/**
24
* Schema for text nodes - the leaf nodes containing actual text content
25
*/
26
const textSchema: $node<'text'>;
27
```
28
29
### Paragraph
30
31
Standard paragraph nodes for regular text content.
32
33
```typescript { .api }
34
/**
35
* HTML attributes for paragraph nodes
36
*/
37
const paragraphAttr: $nodeAttr<'paragraph'>;
38
39
/**
40
* Schema definition for paragraph nodes
41
*/
42
const paragraphSchema: $nodeSchema<'paragraph'>;
43
44
/**
45
* Command to convert current selection to paragraph
46
*/
47
const turnIntoTextCommand: $command<'TurnIntoText'>;
48
49
/**
50
* Keyboard shortcuts for paragraph operations
51
* - Mod-Alt-0: Convert to paragraph
52
*/
53
const paragraphKeymap: $useKeymap;
54
```
55
56
### Headings
57
58
Heading nodes supporting levels 1-6 with automatic ID generation.
59
60
```typescript { .api }
61
/**
62
* Context slice for generating heading IDs from node content
63
* Default implementation converts text to lowercase with dashes
64
*/
65
const headingIdGenerator: $ctx<(node: Node) => string>;
66
67
/**
68
* HTML attributes for heading nodes
69
*/
70
const headingAttr: $nodeAttr<'heading'>;
71
72
/**
73
* Schema for heading nodes (h1-h6) with id and level attributes
74
*/
75
const headingSchema: $nodeSchema<'heading'>;
76
77
/**
78
* Input rule for creating headings using # syntax
79
* # = h1, ## = h2, etc.
80
*/
81
const wrapInHeadingInputRule: $inputRule;
82
83
/**
84
* Command to wrap selection in heading of specified level
85
*/
86
const wrapInHeadingCommand: $command<'WrapInHeading'>;
87
88
/**
89
* Command to downgrade heading level (h1 -> h2, etc.)
90
*/
91
const downgradeHeadingCommand: $command<'DowngradeHeading'>;
92
93
/**
94
* Keyboard shortcuts for heading operations
95
* - Mod-Alt-1 through Mod-Alt-6: Create headings
96
* - Delete/Backspace: Special handling at heading boundaries
97
*/
98
const headingKeymap: $useKeymap;
99
```
100
101
**Usage Examples:**
102
103
```typescript
104
import { Editor } from "@milkdown/core";
105
import { headingSchema, wrapInHeadingCommand } from "@milkdown/preset-commonmark";
106
107
// Use heading command programmatically
108
editor.action((ctx) => {
109
const cmd = ctx.get(wrapInHeadingCommand.key);
110
cmd({ level: 2 }); // Create h2 heading
111
});
112
```
113
114
### Blockquotes
115
116
Quote blocks for highlighting quoted content.
117
118
```typescript { .api }
119
/**
120
* HTML attributes for blockquote nodes
121
*/
122
const blockquoteAttr: $nodeAttr<'blockquote'>;
123
124
/**
125
* Schema definition for blockquote nodes
126
*/
127
const blockquoteSchema: $nodeSchema<'blockquote'>;
128
129
/**
130
* Input rule for creating blockquotes using > prefix
131
*/
132
const wrapInBlockquoteInputRule: $inputRule;
133
134
/**
135
* Command to wrap selection in blockquote
136
*/
137
const wrapInBlockquoteCommand: $command<'WrapInBlockquote'>;
138
139
/**
140
* Keyboard shortcuts for blockquote operations
141
* - Mod-Shift-b: Toggle blockquote
142
*/
143
const blockquoteKeymap: $useKeymap;
144
```
145
146
### Code Blocks
147
148
Multi-line code blocks with language specification.
149
150
```typescript { .api }
151
/**
152
* HTML attributes for code block nodes
153
*/
154
const codeBlockAttr: $nodeAttr<'codeBlock'>;
155
156
/**
157
* Schema for code block nodes with language attribute
158
*/
159
const codeBlockSchema: $nodeSchema<'code_block'>;
160
161
/**
162
* Input rule for creating code blocks using ``` syntax
163
*/
164
const createCodeBlockInputRule: $inputRule;
165
166
/**
167
* Command to create code block with optional language
168
*/
169
const createCodeBlockCommand: $command<'CreateCodeBlock'>;
170
171
/**
172
* Command to update language of existing code block
173
*/
174
const updateCodeBlockLanguageCommand: $command<'UpdateCodeBlockLanguage'>;
175
176
/**
177
* Keyboard shortcuts for code block operations
178
* - Mod-Alt-c: Create code block
179
*/
180
const codeBlockKeymap: $useKeymap;
181
```
182
183
**Usage Examples:**
184
185
```typescript
186
import { createCodeBlockCommand } from "@milkdown/preset-commonmark";
187
188
// Create code block with language
189
editor.action((ctx) => {
190
const cmd = ctx.get(createCodeBlockCommand.key);
191
cmd({ language: "typescript" });
192
});
193
```
194
195
### Images
196
197
Inline and block image nodes with alt text and titles.
198
199
```typescript { .api }
200
/**
201
* HTML attributes for image nodes
202
*/
203
const imageAttr: $nodeAttr<'image'>;
204
205
/**
206
* Schema for image nodes with src, alt, and title attributes
207
*/
208
const imageSchema: $nodeSchema<'image'>;
209
210
/**
211
* Command payload interface for image operations
212
*/
213
interface UpdateImageCommandPayload {
214
src?: string;
215
title?: string;
216
alt?: string;
217
}
218
219
/**
220
* Command to insert new image at cursor position
221
*/
222
const insertImageCommand: $command<'InsertImage'>;
223
224
/**
225
* Command to update properties of selected image
226
*/
227
const updateImageCommand: $command<'UpdateImage'>;
228
229
/**
230
* Input rule for creating images using  syntax
231
*/
232
const insertImageInputRule: $inputRule;
233
```
234
235
### Hard Breaks
236
237
Line breaks within paragraphs and other text content.
238
239
```typescript { .api }
240
/**
241
* HTML attributes for hard break nodes
242
*/
243
const hardbreakAttr: $nodeAttr<'hardbreak'>;
244
245
/**
246
* Schema for hard break nodes with isInline attribute
247
*/
248
const hardbreakSchema: $nodeSchema<'hardbreak'>;
249
250
/**
251
* Command to insert hard break at cursor position
252
*/
253
const insertHardbreakCommand: $command<'InsertHardbreak'>;
254
255
/**
256
* Keyboard shortcuts for hard break operations
257
* - Shift-Enter: Insert hard break
258
*/
259
const hardbreakKeymap: $useKeymap;
260
```
261
262
### Horizontal Rules
263
264
Thematic breaks represented as horizontal lines.
265
266
```typescript { .api }
267
/**
268
* HTML attributes for horizontal rule nodes
269
*/
270
const hrAttr: $nodeAttr<'hr'>;
271
272
/**
273
* Schema definition for horizontal rule nodes
274
*/
275
const hrSchema: $nodeSchema<'hr'>;
276
277
/**
278
* Input rules for creating horizontal rules
279
* Supports ---, ___, and *** syntax
280
*/
281
const insertHrInputRule: $inputRule;
282
283
/**
284
* Command to insert horizontal rule at cursor position
285
*/
286
const insertHrCommand: $command<'InsertHr'>;
287
```
288
289
### Lists
290
291
Bullet and ordered lists with full nesting support.
292
293
```typescript { .api }
294
/**
295
* HTML attributes for bullet list nodes
296
*/
297
const bulletListAttr: $nodeAttr<'bulletList'>;
298
299
/**
300
* Schema for bullet list nodes with spread attribute
301
*/
302
const bulletListSchema: $nodeSchema<'bullet_list'>;
303
304
/**
305
* Input rules for creating bullet lists using *, -, or + syntax
306
*/
307
const wrapInBulletListInputRule: $inputRule;
308
309
/**
310
* Command to wrap selection in bullet list
311
*/
312
const wrapInBulletListCommand: $command<'WrapInBulletList'>;
313
314
/**
315
* Keyboard shortcuts for bullet list operations
316
* - Mod-Alt-8: Create bullet list
317
*/
318
const bulletListKeymap: $useKeymap;
319
320
/**
321
* HTML attributes for ordered list nodes
322
*/
323
const orderedListAttr: $nodeAttr<'orderedList'>;
324
325
/**
326
* Schema for ordered list nodes with order and spread attributes
327
*/
328
const orderedListSchema: $nodeSchema<'ordered_list'>;
329
330
/**
331
* Input rule for creating numbered lists using 1. syntax
332
*/
333
const wrapInOrderedListInputRule: $inputRule;
334
335
/**
336
* Command to wrap selection in ordered list
337
*/
338
const wrapInOrderedListCommand: $command<'WrapInOrderedList'>;
339
340
/**
341
* Keyboard shortcuts for ordered list operations
342
* - Mod-Alt-7: Create ordered list
343
*/
344
const orderedListKeymap: $useKeymap;
345
```
346
347
### List Items
348
349
Individual items within lists with indentation support.
350
351
```typescript { .api }
352
/**
353
* HTML attributes for list item nodes
354
*/
355
const listItemAttr: $nodeAttr<'listItem'>;
356
357
/**
358
* Schema for list item nodes with label, listType, and spread attributes
359
*/
360
const listItemSchema: $nodeSchema<'list_item'>;
361
362
/**
363
* Command to indent (sink) list item to deeper level
364
*/
365
const sinkListItemCommand: $command<'SinkListItem'>;
366
367
/**
368
* Command to unindent (lift) list item to shallower level
369
*/
370
const liftListItemCommand: $command<'LiftListItem'>;
371
372
/**
373
* Command to split current list item at cursor position
374
*/
375
const splitListItemCommand: $command<'SplitListItem'>;
376
377
/**
378
* Command to lift first list item out of list
379
*/
380
const liftFirstListItemCommand: $command<'LiftFirstListItem'>;
381
382
/**
383
* Keyboard shortcuts for list item operations
384
* - Enter: Split list item
385
* - Tab: Indent list item
386
* - Shift-Tab: Unindent list item
387
* - Mod-[: Unindent list item
388
* - Mod-]: Indent list item
389
* - Backspace/Delete: Special handling at item boundaries
390
*/
391
const listItemKeymap: $useKeymap;
392
```
393
394
### HTML Nodes
395
396
Inline HTML content preservation.
397
398
```typescript { .api }
399
/**
400
* HTML attributes for HTML nodes
401
*/
402
const htmlAttr: $nodeAttr<'html'>;
403
404
/**
405
* Schema for inline HTML nodes with value attribute
406
*/
407
const htmlSchema: $nodeSchema<'html'>;
408
```
409
410
**Usage Examples:**
411
412
```typescript
413
import {
414
bulletListSchema,
415
wrapInBulletListCommand,
416
sinkListItemCommand
417
} from "@milkdown/preset-commonmark";
418
419
// Create nested list structure
420
editor.action((ctx) => {
421
const wrapCmd = ctx.get(wrapInBulletListCommand.key);
422
const sinkCmd = ctx.get(sinkListItemCommand.key);
423
424
wrapCmd(); // Create bullet list
425
sinkCmd(); // Indent current item
426
});
427
```