0
# Utility Plugins
1

2
Advanced editing behaviors including remark transformers for markdown processing and ProseMirror plugins for cursor handling and content synchronization. These plugins provide essential functionality for a smooth editing experience.
3

4
## Capabilities
5

6
### Remark Plugins
7

8
Remark plugins handle markdown parsing and serialization, ensuring proper conversion between markdown text and the editor's internal representation.
9

10
```typescript { .api }
11
/**
12
 * Adds order attributes to list items during markdown processing
13
 * Ensures proper numbering in ordered lists
14
 */
15
const remarkAddOrderInListPlugin: $remark<'remarkAddOrderInList'>;
16

17
/**
18
 * Handles inline line breaks during markdown transformation
19
 * Converts hard breaks to proper editor nodes
20
 */
21
const remarkLineBreak: $remark<'remarkLineBreak'>;
22

23
/**
24
 * Wraps the remark-inline-links plugin for processing inline link syntax
25
 * Converts reference-style links to inline format
26
 */
27
const remarkInlineLinkPlugin: $remark<'remarkInlineLink'>;
28

29
/**
30
 * Transforms HTML nodes during markdown processing
31
 * Handles inline HTML content preservation
32
 */
33
const remarkHtmlTransformer: $remark<'remarkHTMLTransformer'>;
34

35
/**
36
 * Preserves original emphasis and strong markers (* vs _ and ** vs __)
37
 * Maintains consistency with user's preferred markdown syntax
38
 */
39
const remarkMarker: $remark<'remarkMarker'>;
40

41
/**
42
 * Preserves empty lines in markdown output
43
 * Maintains document formatting and readability
44
 */
45
const remarkPreserveEmptyLinePlugin: $remark<'remark-preserve-empty-line'>;
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { 
52
  remarkAddOrderInListPlugin,
53
  remarkLineBreak,
54
  remarkMarker 
55
} from "@milkdown/preset-commonmark";
56

57
// These plugins are automatically included in the commonmark preset
58
// They can also be used individually if needed
59
const customPreset = [
60
  remarkAddOrderInListPlugin,
61
  remarkLineBreak,
62
  remarkMarker,
63
];
64
```
65

66
### ProseMirror Plugins
67

68
ProseMirror plugins provide advanced editor behaviors and work directly with the editor's document model to enhance the editing experience.
69

70
```typescript { .api }
71
/**
72
 * Fixes cursor positioning bug in Chrome 98+ for inline nodes
73
 * Ensures proper cursor placement around images, links, and other inline elements
74
 */
75
const inlineNodesCursorPlugin: $prose;
76

77
/**
78
 * Clears formatting marks around hard break nodes
79
 * Prevents marks from spanning across line breaks inappropriately
80
 */
81
const hardbreakClearMarkPlugin: $prose;
82

83
/**
84
 * Context configuration for nodes that should be filtered during hardbreak insertion
85
 * Array of node type names where hardbreaks should not be automatically inserted
86
 */
87
const hardbreakFilterNodes: $ctx<string[]>;
88

89
/**
90
 * Filters hardbreak insertion based on current context
91
 * Uses hardbreakFilterNodes context to determine where hardbreaks are allowed
92
 */
93
const hardbreakFilterPlugin: $prose;
94

95
/**
96
 * Synchronizes heading node IDs with their text content
97
 * Automatically updates heading IDs when heading text changes
98
 */
99
const syncHeadingIdPlugin: $prose;
100

101
/**
102
 * Synchronizes order attributes in list items
103
 * Maintains proper numbering in ordered lists during editing
104
 */
105
const syncListOrderPlugin: $prose;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
import { 
112
  hardbreakFilterNodes,
113
  hardbreakFilterPlugin,
114
  syncHeadingIdPlugin 
115
} from "@milkdown/preset-commonmark";
116

117
// Configure hardbreak filtering
118
editor.config((ctx) => {
119
  ctx.set(hardbreakFilterNodes.key, ['codeBlock', 'heading']);
120
});
121

122
// The sync plugins work automatically once included
123
const customPlugins = [
124
  hardbreakFilterPlugin,
125
  syncHeadingIdPlugin,
126
];
127
```
128

129
### Plugin Integration
130

131
All utility plugins are designed to work seamlessly together and are included in the main commonmark preset. They can also be used individually for custom configurations.
132

133
```typescript { .api }
134
/**
135
 * Combined utility plugins included in the commonmark preset
136
 * Contains all remark and ProseMirror plugins for full functionality
137
 */
138
const plugins: MilkdownPlugin[];
139
```
140

141
**Complete Integration Example:**
142

143
```typescript
144
import { Editor } from "@milkdown/core";
145
import { 
146
  remarkAddOrderInListPlugin,
147
  remarkLineBreak,
148
  inlineNodesCursorPlugin,
149
  syncHeadingIdPlugin,
150
  hardbreakFilterNodes
151
} from "@milkdown/preset-commonmark";
152

153
// Custom editor with specific plugins
154
const editor = await Editor.make()
155
  .config((ctx) => {
156
    // Configure hardbreak filtering
157
    ctx.set(hardbreakFilterNodes.key, ['codeBlock']);
158
  })
159
  .use([
160
    // Remark plugins for markdown processing
161
    remarkAddOrderInListPlugin,
162
    remarkLineBreak,
163
    
164
    // ProseMirror plugins for editor behavior
165
    inlineNodesCursorPlugin,
166
    syncHeadingIdPlugin,
167
  ])
168
  .create();
169
```
170

171
## Plugin Categories
172

173
### Content Processing Plugins
174

175
Handle the transformation and processing of content:
176

177
- `remarkAddOrderInListPlugin` - List ordering
178
- `remarkLineBreak` - Line break handling  
179
- `remarkHtmlTransformer` - HTML content processing
180
- `remarkMarker` - Markdown syntax preservation
181
- `remarkPreserveEmptyLinePlugin` - Whitespace preservation
182

183
### Editor Behavior Plugins
184

185
Enhance the editing experience and fix browser-specific issues:
186

187
- `inlineNodesCursorPlugin` - Cursor positioning fixes
188
- `hardbreakClearMarkPlugin` - Mark cleanup around breaks
189
- `hardbreakFilterPlugin` - Context-aware hardbreak insertion
190

191
### Content Synchronization Plugins
192

193
Keep document properties synchronized during editing:
194

195
- `syncHeadingIdPlugin` - Heading ID management
196
- `syncListOrderPlugin` - List numbering consistency
197

198
## Types
199

200
```typescript { .api }
201
// Plugin types
202
type $remark<T> = any; // Remark plugin type
203
type $prose = any; // ProseMirror plugin type
204
type $ctx<T> = any; // Context configuration type
205
type MilkdownPlugin = any; // Core plugin type
206

207
// Context value types
208
type HardbreakFilterNodes = string[]; // Array of node type names
209
```