0
# Editor Commands
1

2
Programmatic control over editor content including formatting, node manipulation, and cursor positioning. Commands provide a consistent API for all editor operations and can be triggered programmatically or via keyboard shortcuts.
3

4
## Capabilities
5

6
### Selection and State Commands
7

8
Commands for querying and manipulating the current selection state.
9

10
```typescript { .api }
11
/**
12
 * Check if a specific mark is currently selected/active at cursor position
13
 * @param markType - Optional mark type to check, defaults to checking any mark
14
 * @returns boolean indicating if mark is active
15
 */
16
const isMarkSelectedCommand: $command<'IsMarkSelected'>;
17

18
/**
19
 * Check if a specific node type is currently selected
20
 * @param nodeType - Optional node type to check, defaults to checking any node
21
 * @returns boolean indicating if node is selected
22
 * Note: Actual command key is 'IsNoteSelected' (typo in source code)
23
 */
24
const isNodeSelectedCommand: $command<'IsNoteSelected'>;
25

26
/**
27
 * Select text near a specific position in the document
28
 * @param pos - Position in document (required, command returns false if not provided)
29
 */
30
const selectTextNearPosCommand: $command<'SelectTextNearPos'>;
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import { 
37
  isMarkSelectedCommand,
38
  isNodeSelectedCommand 
39
} from "@milkdown/preset-commonmark";
40

41
// Check if emphasis is currently active
42
editor.action((ctx) => {
43
  const isMarkSelected = ctx.get(isMarkSelectedCommand.key);
44
  const emphasisActive = isMarkSelected(); // Check current mark state
45
});
46
```
47

48
### Content Manipulation Commands
49

50
Commands for modifying document content and structure.
51

52
```typescript { .api }
53
/**
54
 * Clear all text content in the current block node
55
 * Preserves block structure while removing text
56
 */
57
const clearTextInCurrentBlockCommand: $command<'ClearTextInCurrentBlock'>;
58

59
/**
60
 * Set the type of the current block to a specific node type
61
 * @param nodeType - Target node type to convert to
62
 * @param attrs - Optional attributes for the new node
63
 */
64
const setBlockTypeCommand: $command<'SetBlockType'>;
65

66
/**
67
 * Wrap the current selection in a specific block type
68
 * @param nodeType - Node type to wrap selection with
69
 * @param attrs - Optional attributes for the wrapper node
70
 */
71
const wrapInBlockTypeCommand: $command<'WrapInBlockType'>;
72

73
/**
74
 * Add a new block of specified type at the cursor position
75
 * @param nodeType - Node type or Node instance to insert
76
 * @param attrs - Optional attributes for the new node
77
 */
78
const addBlockTypeCommand: $command<'AddBlockType'>;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { 
85
  setBlockTypeCommand,
86
  wrapInBlockTypeCommand,
87
  addBlockTypeCommand
88
} from "@milkdown/preset-commonmark";
89

90
// Convert current block to heading
91
editor.action((ctx) => {
92
  const setBlockType = ctx.get(setBlockTypeCommand.key);
93
  setBlockType({
94
    nodeType: ctx.get(headingSchema.type),
95
    attrs: { level: 2 }
96
  });
97
});
98

99
// Wrap selection in blockquote
100
editor.action((ctx) => {
101
  const wrapInBlockType = ctx.get(wrapInBlockTypeCommand.key);
102
  wrapInBlockType({
103
    nodeType: ctx.get(blockquoteSchema.type)
104
  });
105
});
106
```
107

108
### Node-Specific Commands
109

110
Commands specific to particular node types, organized by functionality.
111

112
#### Heading Commands
113

114
```typescript { .api }
115
/**
116
 * Wrap current selection or line in heading of specified level
117
 * @param level - Heading level (1-6), defaults to 1
118
 */
119
const wrapInHeadingCommand: $command<'WrapInHeading'>;
120

121
/**
122
 * Downgrade current heading by one level (h1 -> h2, etc.)
123
 * Does nothing if not in a heading or already at h6
124
 */
125
const downgradeHeadingCommand: $command<'DowngradeHeading'>;
126
```
127

128
#### Text Formatting Commands
129

130
```typescript { .api }
131
/**
132
 * Toggle emphasis (italic) formatting on current selection
133
 */
134
const toggleEmphasisCommand: $command<'ToggleEmphasis'>;
135

136
/**
137
 * Toggle strong (bold) formatting on current selection
138
 */
139
const toggleStrongCommand: $command<'ToggleStrong'>;
140

141
/**
142
 * Toggle inline code formatting on current selection
143
 */
144
const toggleInlineCodeCommand: $command<'ToggleInlineCode'>;
145

146
/**
147
 * Toggle link mark on current selection
148
 * @param payload - Link properties (href, title)
149
 */
150
const toggleLinkCommand: $command<'ToggleLink'>;
151

152
/**
153
 * Update properties of existing link at cursor position
154
 * @param payload - Updated link properties
155
 */
156
const updateLinkCommand: $command<'UpdateLink'>;
157
```
158

159
#### List Commands
160

161
```typescript { .api }
162
/**
163
 * Wrap current selection in bullet list
164
 */
165
const wrapInBulletListCommand: $command<'WrapInBulletList'>;
166

167
/**
168
 * Wrap current selection in ordered (numbered) list
169
 */
170
const wrapInOrderedListCommand: $command<'WrapInOrderedList'>;
171

172
/**
173
 * Indent current list item to deeper nesting level
174
 */
175
const sinkListItemCommand: $command<'SinkListItem'>;
176

177
/**
178
 * Unindent current list item to shallower nesting level
179
 */
180
const liftListItemCommand: $command<'LiftListItem'>;
181

182
/**
183
 * Split current list item at cursor position
184
 */
185
const splitListItemCommand: $command<'SplitListItem'>;
186

187
/**
188
 * Lift first list item out of its containing list
189
 */
190
const liftFirstListItemCommand: $command<'LiftFirstListItem'>;
191
```
192

193
#### Block Element Commands
194

195
```typescript { .api }
196
/**
197
 * Wrap current selection in blockquote
198
 */
199
const wrapInBlockquoteCommand: $command<'WrapInBlockquote'>;
200

201
/**
202
 * Create code block at cursor position
203
 * @param language - Optional programming language for syntax highlighting
204
 */
205
const createCodeBlockCommand: $command<'CreateCodeBlock'>;
206

207
/**
208
 * Update language of existing code block
209
 * @param pos - Position of code block to update
210
 * @param language - New language identifier
211
 */
212
const updateCodeBlockLanguageCommand: $command<'UpdateCodeBlockLanguage'>;
213

214
/**
215
 * Convert current block to paragraph
216
 */
217
const turnIntoTextCommand: $command<'TurnIntoText'>;
218
```
219

220
#### Media Commands
221

222
```typescript { .api }
223
/**
224
 * Insert image at cursor position
225
 * @param payload - Image properties (src, alt, title)
226
 */
227
const insertImageCommand: $command<'InsertImage'>;
228

229
/**
230
 * Update properties of selected image
231
 * @param payload - Updated image properties
232
 */
233
const updateImageCommand: $command<'UpdateImage'>;
234

235
/**
236
 * Insert hard break (line break) at cursor position
237
 */
238
const insertHardbreakCommand: $command<'InsertHardbreak'>;
239

240
/**
241
 * Insert horizontal rule at cursor position
242
 */
243
const insertHrCommand: $command<'InsertHr'>;
244
```
245

246
## Command Usage Patterns
247

248
### Basic Command Execution
249

250
```typescript
251
import { toggleEmphasisCommand } from "@milkdown/preset-commonmark";
252

253
editor.action((ctx) => {
254
  const command = ctx.get(toggleEmphasisCommand.key);
255
  command(); // Execute command
256
});
257
```
258

259
### Commands with Parameters
260

261
```typescript
262
import { 
263
  wrapInHeadingCommand,
264
  createCodeBlockCommand,
265
  insertImageCommand 
266
} from "@milkdown/preset-commonmark";
267

268
editor.action((ctx) => {
269
  // Heading with level
270
  const headingCmd = ctx.get(wrapInHeadingCommand.key);
271
  headingCmd({ level: 3 });
272
  
273
  // Code block with language
274
  const codeCmd = ctx.get(createCodeBlockCommand.key);
275
  codeCmd({ language: "typescript" });
276
  
277
  // Image with properties
278
  const imageCmd = ctx.get(insertImageCommand.key);
279
  imageCmd({
280
    src: "/path/to/image.png",
281
    alt: "Description",
282
    title: "Image Title"
283
  });
284
});
285
```
286

287
### Command State Queries
288

289
```typescript
290
import { isMarkSelectedCommand, isNodeSelectedCommand } from "@milkdown/preset-commonmark";
291

292
editor.action((ctx) => {
293
  const isMarkSelected = ctx.get(isMarkSelectedCommand.key);
294
  const isNodeSelected = ctx.get(isNodeSelectedCommand.key);
295
  
296
  // Check current state
297
  const hasEmphasis = isMarkSelected(); // Any mark active
298
  const inHeading = isNodeSelected(); // Any node selected
299
  
300
  // Use state for conditional logic
301
  if (!hasEmphasis) {
302
    const toggleCmd = ctx.get(toggleEmphasisCommand.key);
303
    toggleCmd();
304
  }
305
});
306
```
307

308
## Types
309

310
```typescript { .api }
311
// Command types
312
type $command<T> = any; // Command definition type
313

314
// Node and mark types from ProseMirror
315
type NodeType = any;
316
type MarkType = any;
317
type Node = any;
318
type Attrs = Record<string, any>;
319

320
// Command parameter interfaces
321
interface SetBlockTypeCommandPayload {
322
  nodeType: NodeType;
323
  attrs?: Attrs;
324
}
325

326
interface WrapInBlockTypeCommandPayload {
327
  nodeType: NodeType;
328
  attrs?: Attrs;
329
}
330

331
interface AddBlockTypeCommandPayload {
332
  nodeType: NodeType | Node;
333
  attrs?: Attrs;
334
}
335

336
interface SelectTextNearPosCommandPayload {
337
  pos?: number;
338
}
339

340
interface WrapInHeadingCommandPayload {
341
  level?: number;
342
}
343

344
interface CreateCodeBlockCommandPayload {
345
  language?: string;
346
}
347

348
interface UpdateCodeBlockLanguageCommandPayload {
349
  pos: number;
350
  language: string;
351
}
352

353
interface UpdateImageCommandPayload {
354
  src?: string;
355
  title?: string;
356
  alt?: string;
357
}
358

359
interface UpdateLinkCommandPayload {
360
  href?: string;
361
  title?: string;
362
}
363
```