@dragon708/docmind-markdown

Convierte StructuredDocumentResult (modelo compartido de DocMind) en Markdown (GFM), texto orientado a LLM y secciones/chunks con Markdown opcional por trozo. Expone extractMarkdown: un router unificado sobre estructurado, bytes o ruta (Node) que delega en DOCX (Mammoth → Turndown), PDF y formatos HTML / CSV / Excel mediante el motor de conversión a Markdown integrado (solo en Node), con fallback a serialización estructurada cuando la ruta especializada no aplica o falla.

Instalación

npm install @dragon708/docmind-markdown

Dependencias destacadas: @dragon708/docmind-shared, cadena de conversión a Markdown empaquetada con el paquete, mammoth, turndown, turndown-plugin-gfm. La lógica es Node-first; en navegador puro las rutas binarias pesadas y parte de DOCX bytes no están disponibles (ver mensajes unsupported-runtime / warnings).

Módulos conceptuales

| Área | Entradas principales | Salida | |------|----------------------|--------| | Structured → MD | StructuredDocumentResult | convertStructuredToMarkdown / renderMarkdown | | Structured → LLM text | Mismo envelope | convertStructuredToLlmText / renderLlmText / alias extractLlmContent | | Chunks | Structured + opciones | splitStructuredIntoChunks / renderMarkdownSections / extractStructuredChunks | | DOCX bytes → MD | Buffer/path | convertDocxToMarkdown (Mammoth + Turndown + GFM) | | PDF bytes → MD | Buffer/path | convertPdfToMarkdown (motor integrado en Node) | | HTML / CSV / XLSX | Bytes/path/text | convertHtmlToMarkdown, convertCsvToMarkdown, convertSpreadsheetToMarkdown | | Router único | structured | bytes | path | extractMarkdown |

Uso rápido

Desde documento estructurado

import { convertStructuredToMarkdown, renderMarkdown } from "@dragon708/docmind-markdown";

const md = convertStructuredToMarkdown(structured, {
  appendUnreferencedTables: true,
  pageTransitionMarkers: true,
});
// renderMarkdown es alias del mismo símbolo

Texto para LLM (no es Markdown)

import { renderLlmText } from "@dragon708/docmind-markdown";

const plain = renderLlmText(structured, { compact: true });

Trozos con Markdown por sección

import { renderMarkdownSections } from "@dragon708/docmind-markdown";

const sections = await renderMarkdownSections(structured, {
  maxChars: 4000,
  chunks: { includeMarkdown: true, preserveTables: true },
});

extractMarkdown unificado (Node con bytes)

import { extractMarkdown } from "@dragon708/docmind-markdown";

const result = await extractMarkdown(
  { data: buffer, filename: "informe.pdf" },
  {
    structuredFallback: structured,
    pdf: { /* opciones del conversor PDF → Markdown */ },
  },
);

console.log(result.markdown);
console.log(result.strategy, result.warnings, result.routing);

Opciones frecuentes (ver tipos ExtractMarkdownOptions):

• structuredFallback: envelope si la ruta especializada falla o está vacía.
• markdown: opciones de convertStructuredToMarkdown en fallback.
• docx / pdf / html / csv / spreadsheet: knobs por formato binario (p. ej. markdownSpreadsheet.maxRowsPerSheet, includeSheetNames, compactMode).
• Post-proceso Excel: las tablas GFM “atascadas” en una sola línea se normalizan en el paquete (filas separadas por \n) antes de devolver el string.

Conversores directos por formato

import {
  convertDocxToMarkdown,
  convertPdfToMarkdown,
  convertHtmlToMarkdown,
  convertCsvToMarkdown,
  convertSpreadsheetToMarkdown,
} from "@dragon708/docmind-markdown";

// Cada uno devuelve markdown, warnings y origen (p. ej. ruta especializada vs fallback estructurado)

Detección de binario

import { detectBinaryFormat } from "@dragon708/docmind-markdown";

const fmt = detectBinaryFormat(bytes, "archivo.bin", mimeType);

HTML: cadena vs ruta

import { looksLikeHtmlString } from "@dragon708/docmind-markdown";

if (looksLikeHtmlString(input)) {
  // Tratar como markup, no como path
}

Estrategias y routing (extractMarkdown)

El resultado puede incluir:

• strategy: qué ruta tomó el router (identificadores tipo pdf-*-specialized, spreadsheet-structured-fallback, etc.; ver tipos exportados).
• warnings: trazas legibles ([docmind-markdown:extractMarkdown], etc.).
• routing: resumen opcional (routingSummary, detectedFormat, specializedPipeline, usedStructuredFallback, mediaHint).

Útil para telemetría y UI de depuración (p. ej. playground).

CSV y hojas de cálculo

• Preparación de CSV (módulo tabular): cabecera sintética, maxRows, etc., antes de la conversión.
• convertSpreadsheetToMarkdown: tras la conversión desde hoja de cálculo, opciones includeSheetNames, compactMode, maxRowsPerSheet vía limitSpreadsheetMarkdownRowsPerSheet.
• splitJammedSpreadsheetPipeTableLines: corrige tablas GFM en una sola línea antes de devolver el Markdown.

Empaquetado y prepack

El package.json define scripts prepack que validan y copian dependencias vendoradas del runtime de conversión para que el tarball npm sea autocontenido. Si desarrollas en el monorepo, ejecuta npm run build antes de npm pack / publicar.

Seguridad

• El Markdown y el HTML intermedio (DOCX) pueden contener contenido hostil. Sanitiza antes de dangerouslySetInnerHTML o equivalentes.
• No confíes en documentos arbitrarios para conversión sin cuarentena en servidor.

Paquetes relacionados

| Paquete | Rol | |---------|-----| | @dragon708/docmind-node | Cliente que llama a extractMarkdown con structuredFallback cableado | | @dragon708/docmind-browser | Mismas firmas; sin conversión binaria pesada en el cliente | | @dragon708/docmind-shared | StructuredDocumentResult |

Licencia

MIT (monorepo DocMind).