HTML to Tiptap conversion in Node.js
- Use jsdom and a Node.js pipeline to convert legacy HTML directly into structured JSON for the Tiptap schema.
- The system produces three main artifacts per processed file: the Tiptap document as JSON, a metadata log, and a DOM snapshot.
- Keep a registry of processed files based on mtime and size to avoid unnecessary reprocessing and duplicates.
- The conversion runs 100% offline using rules and heuristics based on CSS classes and HTML structure, with optional LLM support.
Converting legacy HTML into structured JSON for Tiptap tends to be a frustrating obstacle for any developer. To get past it without the headache, you can build a straightforward Node.js pipeline that uses jsdom to parse the markup and precise heuristics to map each element directly onto the ProseMirror schema.
Main flow
HTML → jsdom → walk the DOM → map elements → Tiptap JSONOutput types
Conversion artifacts
Tiptap document
JSON
Complete structured document with type: "doc".
Metadata
Log
Run data with timestamps and node counts.
DOM Snapshot
HTML
Parsed version of the HTML, used for debugging.
Each processed file produces three separate outputs for use and debugging.
| Artifact | Description |
|---|---|
| JSON | Complete Tiptap document with type: "doc" |
| Log | Processing metadata (timestamps, node counts) |
| DOM Snapshot | Parsed HTML (for debugging) |
Duplicate prevention
The registry at converted/processed-files.json keeps a record of every processed file:
{
"version": 1,
"lastRun": "2026-07-16T06:39:12.359Z",
"files": {
"/path/html/article.html": {
"processedAt": "2026-07-16T06:39:12.661Z",
"mtimeMs": 1784181125106,
"size": 71799,
"outputJson": "/path/converted/json/article.json",
"status": "success"
}
}
}On subsequent runs, files whose mtime and size have not changed are skipped. If a file is modified, it is reprocessed automatically.
Offline mode
The converter runs 100% offline through heuristics. The architecture supports being extended with an LLM classifier (the llmClassifier field in the code), but today it relies only on rules based on CSS classes and HTML structure.
