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#
HTML → jsdom → percorre DOM → mapear elementos → JSON TiptapTipos 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.
| Artefato | Descrição |
|---|---|
| JSON | Documento Tiptap completo com type: "doc" |
| Log | Metadados do processamento (timestamps, node counts) |
| DOM Snapshot | HTML parseado (para debug) |
Anti-duplicatas#
O sistema de registry em converted/processed-files.json mantém registro de cada arquivo processado:
{
"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.
