0
# Document Structure Management
1
2
Extensions for managing document structure, content flow, and providing history management capabilities.
3
4
## Capabilities
5
6
### Trailing Node Extension
7
8
Automatically maintains document structure by ensuring a trailing node (typically a paragraph) at the end of the document.
9
10
```typescript { .api }
11
/**
12
* Trailing node extension for automatic document structure management
13
*/
14
const TrailingNode: Extension<TrailingNodeOptions>;
15
16
interface TrailingNodeOptions {
17
/** Node type to insert as trailing node (default: 'paragraph') */
18
node: string;
19
/** Node types after which trailing node should not be inserted (default: []) */
20
notAfter?: string | string[];
21
}
22
```
23
24
**Usage Examples:**
25
26
```typescript
27
import { TrailingNode } from "@tiptap/extensions/trailing-node";
28
29
// Basic trailing paragraph
30
const editor = new Editor({
31
extensions: [
32
TrailingNode.configure({
33
node: 'paragraph',
34
}),
35
],
36
});
37
38
// Custom trailing node
39
const customTrailing = TrailingNode.configure({
40
node: 'customBlock',
41
notAfter: ['heading', 'codeBlock'], // Don't add after these node types
42
});
43
44
// Multiple exclusions
45
const selectiveTrailing = TrailingNode.configure({
46
node: 'paragraph',
47
notAfter: ['table', 'image', 'horizontalRule', 'codeBlock'],
48
});
49
```
50
51
**Trailing Node Behavior:**
52
- **Automatic Insertion**: Adds trailing node when document ends with non-excluded node types
53
- **Smart Detection**: Only inserts when necessary to maintain document structure
54
- **Loop Prevention**: Automatically adds configured node type to exclusion list to prevent infinite loops
55
- **Configurable Types**: Support for any node type as the trailing element
56
- **Flexible Exclusions**: String or array of node types to exclude from trailing insertion
57
58
### Undo Redo Extension
59
60
Provides undo and redo functionality with keyboard shortcuts and configurable history management.
61
62
```typescript { .api }
63
/**
64
* Undo/Redo extension with history management and keyboard shortcuts
65
*/
66
const UndoRedo: Extension<UndoRedoOptions>;
67
68
interface UndoRedoOptions {
69
/** Maximum number of history steps to maintain (default: 100) */
70
depth: number;
71
/** Delay in milliseconds before grouping operations (default: 500) */
72
newGroupDelay: number;
73
}
74
75
declare module '@tiptap/core' {
76
interface Commands<ReturnType> {
77
undoRedo: {
78
/** Undo the last operation */
79
undo: () => ReturnType;
80
/** Redo the last undone operation */
81
redo: () => ReturnType;
82
};
83
}
84
}
85
```
86
87
**Usage Examples:**
88
89
```typescript
90
import { UndoRedo } from "@tiptap/extensions/undo-redo";
91
92
// Basic undo/redo
93
const editor = new Editor({
94
extensions: [
95
UndoRedo.configure({
96
depth: 100,
97
newGroupDelay: 500,
98
}),
99
],
100
});
101
102
// Extended history
103
const longHistoryEditor = new Editor({
104
extensions: [
105
UndoRedo.configure({
106
depth: 1000, // Keep more history steps
107
newGroupDelay: 1000, // Group operations over 1 second
108
}),
109
],
110
});
111
112
// Using undo/redo commands
113
editor.commands.undo(); // Undo last operation
114
editor.commands.redo(); // Redo last undone operation
115
116
// Check if undo/redo is available
117
const canUndo = editor.can().undo();
118
const canRedo = editor.can().redo();
119
120
console.log(`Can undo: ${canUndo}, Can redo: ${canRedo}`);
121
```
122
123
**Keyboard Shortcuts:**
124
125
The extension provides built-in keyboard shortcuts:
126
127
- **Undo**:
128
- `Mod-z` (Ctrl-z on Windows/Linux, Cmd-z on Mac)
129
- `Mod-я` (Russian keyboard layout support)
130
- **Redo**:
131
- `Shift-Mod-z` (Shift-Ctrl-z on Windows/Linux, Shift-Cmd-z on Mac)
132
- `Mod-y` (Ctrl-y on Windows/Linux, Cmd-y on Mac)
133
134
**History Management:**
135
136
```typescript
137
// Configure history behavior
138
const editor = new Editor({
139
extensions: [
140
UndoRedo.configure({
141
depth: 50, // Limit history to 50 steps for performance
142
newGroupDelay: 300, // Quick grouping for responsive editing
143
}),
144
],
145
});
146
147
// Manual history management
148
editor.commands.undo(); // Step back one operation
149
editor.commands.redo(); // Step forward one operation
150
151
// Check history state
152
const historyState = editor.state.plugins.find(
153
plugin => plugin.key.name === 'history'
154
);
155
```
156
157
**Important Compatibility Note:**
158
159
⚠️ **The UndoRedo extension is not compatible with collaboration extensions.** Use Tiptap's collaboration-specific history management when working with collaborative editing features.
160
161
### Document Structure Patterns
162
163
Both extensions work together to maintain document integrity:
164
165
```typescript
166
import { TrailingNode, UndoRedo } from "@tiptap/extensions";
167
168
const editor = new Editor({
169
extensions: [
170
// Maintain document structure
171
TrailingNode.configure({
172
node: 'paragraph',
173
notAfter: ['table', 'codeBlock'],
174
}),
175
176
// Enable history with reasonable limits
177
UndoRedo.configure({
178
depth: 200,
179
newGroupDelay: 400,
180
}),
181
],
182
});
183
184
// Document structure operations are tracked in history
185
editor.commands.insertontent('<h1>New Heading</h1>');
186
// TrailingNode automatically adds paragraph after heading
187
// Operation is recorded in history and can be undone
188
189
editor.commands.undo(); // Removes heading and trailing paragraph
190
editor.commands.redo(); // Restores heading and trailing paragraph
191
```
192
193
**Structure Management Benefits:**
194
- **Consistent Documents**: Always maintain expected document structure
195
- **Undo Safety**: Structure changes are properly tracked in history
196
- **User Experience**: Predictable behavior for content editing
197
- **Accessibility**: Better navigation and screen reader support