Tutorials
How to Convert HTML to Tiptap JSON Using jsdom and Heuristics in Node
Featured AnalysisTutorialsNov 11, 2026

How to Convert HTML to Tiptap JSON Using jsdom and Heuristics in Node

Learn how to turn legacy HTML into structured JSON documents for the Tiptap editor using Node.js and jsdom.

Blense+ Featured AnalysisReading: 2 min

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

typescript
HTML → jsdom → walk the DOM → map elements → Tiptap JSON
HTML to Tiptap JSON conversion pipeline
HTML to Tiptap JSON conversion pipeline

Output 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.

ArtifactDescription
JSONComplete Tiptap document with type: "doc"
LogProcessing metadata (timestamps, node counts)
DOM SnapshotParsed HTML (for debugging)

Duplicate prevention

The registry at converted/processed-files.json keeps a record of every processed file:

json
{
  "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.