0
# Milkdown Preset CommonMark
1

2
The @milkdown/preset-commonmark package provides a comprehensive CommonMark preset for the Milkdown WYSIWYG markdown editor framework. It includes all essential plugins needed to support CommonMark specification features including schemas, input rules, commands, keyboard shortcuts, and utility plugins for advanced editing behaviors.
3

4
## Package Information
5

6
- **Package Name**: @milkdown/preset-commonmark
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @milkdown/preset-commonmark`
10

11
## Core Imports
12

13
```typescript
14
import { commonmark } from "@milkdown/preset-commonmark";
15
```
16

17
For individual components:
18

19
```typescript
20
import { 
21
  headingSchema, 
22
  paragraphSchema, 
23
  emphasisSchema,
24
  wrapInHeadingCommand,
25
  toggleEmphasisCommand
26
} from "@milkdown/preset-commonmark";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Editor, rootCtx } from "@milkdown/core";
33
import { commonmark } from "@milkdown/preset-commonmark";
34

35
// Create editor with complete CommonMark support
36
const editor = await Editor.make()
37
  .config((ctx) => {
38
    ctx.set(rootCtx, document.getElementById("editor"));
39
  })
40
  .use(commonmark)
41
  .create();
42
```
43

44
## Architecture
45

46
The preset is organized into several key modules:
47

48
- **Node Schemas**: Document structure definitions (headings, paragraphs, lists, code blocks, images, etc.)
49
- **Mark Schemas**: Inline formatting definitions (emphasis, strong, links, inline code)
50
- **Input Rules**: Automatic markdown-to-editor transformations (typing `#` creates heading, `*text*` creates emphasis)
51
- **Commands**: Programmatic control over editor content and formatting
52
- **Keyboard Shortcuts**: Standard editing shortcuts for all operations
53
- **Utility Plugins**: Advanced behaviors including remark transformers and ProseMirror plugins
54

55
## Capabilities
56

57
### Complete Preset
58

59
The main export that provides everything needed for a full CommonMark editing experience.
60

61
```typescript { .api }
62
/**
63
 * Complete CommonMark preset with all plugins
64
 * Includes: schema, inputRules, markInputRules, commands, keymap, plugins
65
 */
66
const commonmark: MilkdownPlugin[];
67
```
68

69
### Document Structure Nodes
70

71
Core structural elements that form the document hierarchy. Includes headings, paragraphs, lists, code blocks, blockquotes, and more.
72

73
```typescript { .api }
74
// Document root and text nodes
75
const docSchema: $node;
76
const textSchema: $node<'text'>;
77
const paragraphSchema: $nodeSchema<'paragraph'>;
78

79
// Heading nodes with levels 1-6
80
const headingSchema: $nodeSchema<'heading'>;
81
const headingIdGenerator: $ctx<(node: Node) => string>;
82

83
// List structures
84
const bulletListSchema: $nodeSchema<'bullet_list'>;
85
const orderedListSchema: $nodeSchema<'ordered_list'>;
86
const listItemSchema: $nodeSchema<'list_item'>;
87
```
88

89
[Document Nodes](./nodes.md)
90

91
### Text Formatting Marks
92

93
Inline formatting capabilities including emphasis, strong text, links, and inline code.
94

95
```typescript { .api }
96
// Basic formatting marks
97
const emphasisSchema: $markSchema<'emphasis'>;
98
const strongSchema: $markSchema<'strong'>;
99
const inlineCodeSchema: $markSchema<'inlineCode'>;
100

101
// Link mark with href and title attributes
102
const linkSchema: $markSchema<'link'>;
103

104
// Command interfaces for mark manipulation
105
interface UpdateLinkCommandPayload {
106
  href?: string;
107
  title?: string;
108
}
109
```
110

111
[Text Formatting](./marks.md)
112

113
### Interactive Commands
114

115
Programmatic control over editor content including formatting, node manipulation, and cursor positioning.
116

117
```typescript { .api }
118
// Heading commands
119
const wrapInHeadingCommand: $command<'WrapInHeading'>;
120
const downgradeHeadingCommand: $command<'DowngradeHeading'>;
121

122
// Text formatting commands
123
const toggleEmphasisCommand: $command<'ToggleEmphasis'>;
124
const toggleStrongCommand: $command<'ToggleStrong'>;
125
const toggleInlineCodeCommand: $command<'ToggleInlineCode'>;
126

127
// List manipulation commands
128
const wrapInBulletListCommand: $command<'WrapInBulletList'>;
129
const sinkListItemCommand: $command<'SinkListItem'>;
130
const liftListItemCommand: $command<'LiftListItem'>;
131
```
132

133
[Editor Commands](./commands.md)
134

135
### Utility Plugins
136

137
Advanced editing behaviors including remark transformers for markdown processing and ProseMirror plugins for cursor handling and content synchronization.
138

139
```typescript { .api }
140
// Remark plugins for markdown processing
141
const remarkAddOrderInListPlugin: $remark<'remarkAddOrderInList'>;
142
const remarkLineBreak: $remark<'remarkLineBreak'>;
143
const remarkInlineLinkPlugin: $remark<'remarkInlineLink'>;
144

145
// ProseMirror plugins for editor behavior
146
const inlineNodesCursorPlugin: $prose;
147
const syncHeadingIdPlugin: $prose;
148
const hardbreakFilterPlugin: $prose;
149
```
150

151
[Utility Plugins](./plugins.md)
152

153
### Composed Plugin Arrays
154

155
Pre-composed plugin arrays that combine related functionality for convenient use.
156

157
```typescript { .api }
158
/**
159
 * Complete schema array with all node and mark schemas
160
 * Combines all commonmark nodes and marks in proper order
161
 */
162
const schema: MilkdownPlugin[];
163

164
/**
165
 * All node input rules for markdown syntax recognition
166
 * Handles automatic conversion of markdown syntax to nodes
167
 */
168
const inputRules: MilkdownPlugin[];
169

170
/**
171
 * All mark input rules for inline formatting syntax
172
 * Handles conversion of inline markdown formatting to marks
173
 */
174
const markInputRules: MilkdownPlugin[];
175

176
/**
177
 * Complete commands array with all available commands
178
 * Includes all node, mark, and utility commands
179
 */
180
const commands: MilkdownPlugin[];
181

182
/**
183
 * Complete keymap array with all keyboard shortcuts
184
 * Combines all node and mark keymaps
185
 */
186
const keymap: MilkdownPlugin[];
187

188
/**
189
 * Complete plugins array with all utility plugins
190
 * Includes remark and ProseMirror plugins for enhanced functionality
191
 */
192
const plugins: MilkdownPlugin[];
193
```
194

195
### Internal Utilities
196

197
Utility functions for plugin development and content processing.
198

199
```typescript { .api }
200
/**
201
 * Serialize text content from a node during markdown transformation
202
 * Used internally by node serializers
203
 */
204
function serializeText(state: SerializerState, node: Node): void;
205

206
/**
207
 * Add metadata to a plugin for identification and debugging
208
 * @param plugin - The plugin to add metadata to
209
 * @param meta - Metadata object with displayName and optional properties
210
 */
211
function withMeta<T extends MilkdownPlugin>(
212
  plugin: T,
213
  meta: Partial<Meta> & Pick<Meta, 'displayName'>
214
): T;
215
```
216

217
## Types
218

219
```typescript { .api }
220
// Core Milkdown types from dependencies
221
type MilkdownPlugin = any; // From @milkdown/core
222
type Node = any; // From @milkdown/prose
223
type MarkType = any; // From @milkdown/prose
224
type NodeType = any; // From @milkdown/prose
225
type Attrs = Record<string, any>; // From @milkdown/prose
226

227
// Utility types
228
type SerializerState = any; // From @milkdown/transformer
229
type Meta = any; // From @milkdown/utils
230

231
// Command payload interfaces
232
interface UpdateImageCommandPayload {
233
  src?: string;
234
  title?: string;
235
  alt?: string;
236
}
237

238
interface UpdateLinkCommandPayload {
239
  href?: string;
240
  title?: string;
241
}
242
```