0
# HTML Serialization
1

2
Complete HTML serialization and deserialization system with customizable parsing, cleaning utilities, and Slate format conversion.
3

4
## Capabilities
5

6
### HtmlPlugin
7

8
Main plugin that enables HTML serialization and deserialization support in Plate editor.
9

10
```typescript { .api }
11
/**
12
 * HTML plugin for serialization and deserialization
13
 */
14
const HtmlPlugin: SlatePlugin;
15
```
16

17
### deserializeHtml
18

19
Core functionality for converting HTML content into Slate editor format.
20

21
```typescript { .api }
22
/**
23
 * Deserialize HTML content to Slate nodes
24
 * @param editor - Slate editor instance
25
 * @param options - Deserialization options
26
 * @returns Array of Slate nodes
27
 */
28
function deserializeHtml(
29
  editor: SlateEditor, 
30
  options: {
31
    element: HTMLElement | string;
32
    collapseWhiteSpace?: boolean;
33
    defaultElementPlugin?: WithRequiredKey;
34
  }
35
): any[];
36

37
/**
38
 * Deserialize a single HTML element to Slate format
39
 * @param editor - Slate editor instance
40
 * @param element - HTML element to deserialize
41
 * @returns Slate node representation
42
 */
43
function deserializeHtmlElement(
44
  editor: SlateEditor, 
45
  element: HTMLElement
46
): DeserializeHtmlNodeReturnType;
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { createSlateEditor, HtmlPlugin, deserializeHtml } from "@platejs/core";
53

54
const editor = createSlateEditor({
55
  plugins: [HtmlPlugin]
56
});
57

58
// Deserialize HTML string
59
const htmlContent = '<p>Hello <strong>world</strong></p>';
60
const slateNodes = deserializeHtml(editor, { 
61
  element: htmlContent,
62
  collapseWhiteSpace: true 
63
});
64

65
// Deserialize HTML element
66
const element = document.createElement('div');
67
element.innerHTML = '<p>Content</p>';
68
const nodes = deserializeHtml(editor, { element });
69
```
70

71
### serializeHtml
72

73
Convert Slate content to HTML format with customization options.
74

75
```typescript { .api }
76
/**
77
 * Serialize Slate nodes to HTML
78
 * @param editor - Slate editor instance
79
 * @param options - Serialization options
80
 * @returns HTML string representation
81
 */
82
function serializeHtml(
83
  editor: SlateEditor,
84
  options?: { 
85
    nodes?: any[];
86
    dnd?: boolean;
87
    stripDataAttributes?: boolean;
88
  }
89
): string;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
// Serialize current editor content
96
const html = serializeHtml(editor);
97

98
// Serialize specific nodes
99
const html = serializeHtml(editor, {
100
  nodes: [
101
    { type: 'p', children: [{ text: 'Hello world' }] }
102
  ]
103
});
104
```
105

106
### HTML Parsing Functions
107

108
Utilities for parsing HTML strings and converting between formats.
109

110
```typescript { .api }
111
/**
112
 * Parse HTML string to Document
113
 * @param html - HTML string to parse
114
 * @returns Parsed Document object
115
 */
116
function parseHtmlDocument(html: string): Document;
117

118
/**
119
 * Parse HTML string to HTMLElement
120
 * @param html - HTML string to parse
121
 * @returns Parsed HTMLElement
122
 */
123
function parseHtmlElement(html: string): HTMLElement;
124

125
/**
126
 * Convert HTML string to DOM node
127
 * @param rawHtml - Raw HTML string
128
 * @returns HTMLElement node
129
 */
130
function htmlStringToDOMNode(rawHtml: string): HTMLElement;
131
```
132

133
### HTML Cleaning Functions
134

135
Comprehensive HTML cleaning utilities for normalizing content from various sources.
136

137
```typescript { .api }
138
/**
139
 * Clean HTML text nodes by removing unnecessary whitespace
140
 * @param rootNode - Root node to clean
141
 */
142
function cleanHtmlTextNodes(rootNode: Node): void;
143

144
/**
145
 * Clean HTML br elements and normalize line breaks
146
 * @param rootNode - Root node to clean
147
 */
148
function cleanHtmlBrElements(rootNode: Node): void;
149

150
/**
151
 * Collapse whitespace in HTML element according to CSS rules
152
 * @param element - Element to process
153
 * @returns Element with collapsed whitespace
154
 */
155
function collapseWhiteSpace(element: HTMLElement): HTMLElement;
156

157
/**
158
 * Pre-process HTML string before parsing
159
 * @param html - Raw HTML string
160
 * @returns Cleaned HTML string
161
 */
162
function preCleanHtml(html: string): string;
163

164
/**
165
 * Post-process HTML string after serialization
166
 * @param html - HTML string to clean
167
 * @returns Cleaned HTML string
168
 */
169
function postCleanHtml(html: string): string;
170
```
171

172
### HTML Element Classification
173

174
Type guards and utilities for HTML element identification.
175

176
```typescript { .api }
177
/**
178
 * Check if node is an HTML element
179
 * @param node - Node to check
180
 * @returns True if node is Element
181
 */
182
function isHtmlElement(node: Node): node is Element;
183

184
/**
185
 * Check if node is a text node
186
 * @param node - Node to check
187
 * @returns True if node is Text
188
 */
189
function isHtmlText(node: Node): node is Text;
190

191
/**
192
 * Check if element is a block-level element
193
 * @param node - Node to check
194
 * @returns True if block element
195
 */
196
function isHtmlBlockElement(node: Node): boolean;
197

198
/**
199
 * Check if element is an inline element
200
 * @param node - Node to check
201
 * @returns True if inline element
202
 */
203
function isHtmlInlineElement(node: Node): boolean;
204
```
205

206
## HTML Constants
207

208
```typescript { .api }
209
// Character constants for text processing
210
const CARRIAGE_RETURN: string;
211
const LINE_FEED: string;
212
const NO_BREAK_SPACE: string;
213
const SPACE: string;
214
const TAB: string;
215
const ZERO_WIDTH_SPACE: string;
216

217
// HTML element types
218
const BLOCK_ELEMENTS: Set<string>;
219
const INLINE_ELEMENTS: Set<string>;
220
const VOID_ELEMENTS: Set<string>;
221
```
222

223
## Types
224

225
```typescript { .api }
226
type DeserializeHtmlChildren = ChildNode | any | string | null;
227

228
type DeserializeHtmlNodeReturnType = 
229
  | any
230
  | any[]
231
  | DeserializeHtmlChildren[]
232
  | string 
233
  | null;
234

235
interface HtmlDeserializeOptions {
236
  element: HTMLElement | string;
237
  collapseWhiteSpace?: boolean;
238
  defaultElementPlugin?: WithRequiredKey;
239
}
240
```