Tutoriais
Como converter HTML em JSON Tiptap usando jsdom e heurísticas em Node
Análise ExclusivaTutoriais02 de nov. de 2026

Como converter HTML em JSON Tiptap usando jsdom e heurísticas em Node

Descubra como transformar código HTML legado em documentos JSON estruturados para o editor Tiptap usando Node.js e jsdom.

Blense+ Análise ExclusivaLeitura: 2 min

Conversão de HTML para Tiptap em Node.js

  • Utilize jsdom e um pipeline em Node.js para converter HTML legado diretamente em JSON estruturado para o schema do Tiptap.
  • O sistema gera três artefatos principais por arquivo processado: o documento Tiptap em JSON, um log de metadados e um snapshot do DOM.
  • Implemente um registro de arquivos processados baseado em mtime e tamanho para evitar reprocessamentos desnecessários e duplicatas.
  • A conversão roda 100% offline utilizando regras e heurísticas baseadas em classes CSS e estrutura HTML, com suporte opcional a LLMs.

Converter HTML legado em JSON estruturado para o Tiptap costuma ser um obstáculo frustrante para qualquer desenvolvedor. Para resolver isso sem dor de cabeça, você pode implementar um pipeline direto em Node.js que utiliza jsdom para parsear o código e heurísticas precisas para mapear cada elemento diretamente para o schema do ProseMirror.

Fluxo principal#

typescript
HTML → jsdom → percorre DOM → mapear elementos → JSON Tiptap
Pipeline de conversão de HTML para JSON Tiptap

Tipos de saída#

Artefatos da Conversão

Documento Tiptap

JSON

Documento estruturado completo com type: "doc".

Metadados

Log

Dados de execução contendo timestamps e contagem de nós.

DOM Snapshot

HTML

Versão parseada do HTML utilizada para fins de debug.

Cada arquivo processado gera três saídas distintas para uso e debug.

ArtefatoDescrição
JSONDocumento Tiptap completo com type: "doc"
LogMetadados do processamento (timestamps, node counts)
DOM SnapshotHTML parseado (para debug)

Anti-duplicatas#

O sistema de registry em converted/processed-files.json mantém registro de cada arquivo processado:

json
{
  "version": 1,
  "lastRun": "2026-07-16T06:39:12.359Z",
  "files": {
    "/caminho/html/artigo.html": {
      "processedAt": "2026-07-16T06:39:12.661Z",
      "mtimeMs": 1784181125106,
      "size": 71799,
      "outputJson": "/caminho/converted/json/artigo.json",
      "status": "success"
    }
  }
}

Em execuções subsequentes, arquivos cujo mtime e tamanho não mudaram são ignorados. Se o arquivo for modificado, ele é reprocessado automaticamente.

Modo offline#

O conversor roda 100% offline via heurísticas. A arquitetura suporta extensão com LLM classifier (campo llmClassifier no código), mas atualmente utiliza apenas regras baseadas em classes CSS e estrutura HTML.