De Markdown a PDF y de vuelta: qué preserva la conversión de formato
Markdown↔PDF conserva mejor encabezados, listas y tablas simples que los píxeles. Fuentes exactas, paginación y diseño no sobreviven a una ida y vuelta sin pérdida.
Markdown y PDF están optimizados para contratos distintos. Markdown es estructura apta para control de versiones; PDF es una descripción de página fija. Convertir en un sentido y volver es útil, pero no es un ciclo de archivo sin pérdida.
Markdown a PDF: la estructura se convierte en páginas
Markdown a PDF (POST /api/v1/convert/markdown/pdf) acepta un archivo .md o un ZIP que contenga Markdown. Se rechazan las subidas que no sean Markdown ni ZIP, y la entrada .md sin más exige UTF-8. El proceso convierte Markdown a HTML con tablas, tachado y listas de tareas activadas, envuelve ese HTML en CSS orientado a impresión (con pilas de fuentes para varios alfabetos y RTL cuando detecta árabe) y lo imprime a PDF con WeasyPrint.
Lo que suele sobrevivir en el paso de ida:
- Encabezados, párrafos, listas y tablas Markdown sencillas
- Texto en varios alfabetos que la vía HTML sabe maquetar (CJK, latino y otros cubiertos por el CSS de impresión)
- Un PDF imprimible y compartible para flujos de documentación como código
Lo que no:
- Las fuentes del tema de tu editor como coincidencia garantizada en todos los visores
- Los saltos de línea exactos del archivo
.mden pantalla - Funciones interactivas de Markdown sin equivalente en PDF (casillas en vivo, secciones plegables, enlaces wiki)
Una entrada ZIP sirve para empaquetar Markdown con recursos que la vía HTML pueda resolver junto al documento. Es una comodidad de empaquetado, no la garantía de que cada imagen relativa o referencia CSS se vea igual en todos los visores.
PDF a Markdown: entra la capa de texto, sale Markdown
PDF a Markdown (POST /api/v1/convert/pdf/markdown) extrae el contenido textual a Markdown mediante pdf-inspector. La respuesta es text/markdown, descargada como archivo .md. Los PDF nativos digitales con una capa de texto limpia convierten mejor. Las páginas escaneadas sin capa de texto producen un Markdown vacío o inútil hasta que les apliques OCR antes, y el OCR de este sitio también devuelve Markdown, no una capa PDF buscable.
Cabe esperar:
- Encabezados y párrafos cuando las heurísticas de tamaño de fuente aciertan (puede que tengas que renumerar los niveles
#a mano) - Tablas como tablas Markdown cuando el reconocimiento funciona; las maquetaciones a varias columnas pueden linealizarse en otro orden de lectura
- Encabezados y pies de página repetidos en cada página (recórtalos después)
- Imágenes y ecuaciones como dibujos que no se convierten automáticamente en recursos locales ni en LaTeX
Si necesitas prosa sin heurísticas de encabezado, PDF a texto es la extracción más plana. Las exportaciones con forma de tabla que devuelven HTTP 204 indican que no se detectaron bloques de columnas; consulta Exportación de tabla vacía (204).
Qué demuestra en realidad una ida y vuelta
| Sobrevive razonablemente | Normalmente no |
|---|---|
| Palabras, jerarquía de encabezados, estructura de listas | Geometría de página exacta al píxel |
| Tablas sencillas como texto | Fuentes y kerning exactos |
| Un borrador utilizable para Git o agentes | Paginación idéntica a la impresa |
Dar dos vueltas seguidas introduce desviaciones. Markdown→PDF recompone el flujo con WeasyPrint; PDF→Markdown reconstruye la estructura a partir de heurísticas de extracción. Ninguno de los dos pasos guarda un intermedio sin pérdida del modelo de maquetación del otro formato.
Elige una dirección canónica
Si necesitas la maquetación impresa como sistema de registro, conserva el PDF y trata Markdown como exportación o canal para agentes. Si necesitas diffs, revisión de código e ingestión por agentes, prefiere Markdown y trata el PDF como el paso de publicación. No guardes ambos como «fuentes de verdad» equivalentes y esperes que sigan idénticos tras editarlos.
Un ciclo práctico de documentación como código: edita Markdown en Git → usa Markdown a PDF para el artefacto que vas a compartir → evita PDF→Markdown→PDF como rutina diaria. Recurre a PDF→Markdown cuando heredes un PDF nativo digital y necesites texto para un agente; toma ese Markdown como un borrador nuevo, no como garantía de la paginación original.
Los archivos cifrados necesitan un Desbloquear autorizado antes de cualquiera de las dos conversiones. Los archivos dañados que no se pueden analizar deben pasar primero por Get Info / Reparar. Para los mismos endpoints por HTTP, consulta Desarrolladores.