De Markdown a EPUB: guía para autores técnicos

Si escribes documentación técnica, un manual o un libro de programación, probablemente ya lo haces en Markdown: los bloques de código, las tablas y los headings anidados se llevan mejor en texto plano que en un Word lleno de estilos aplicados a mano. El problema aparece cuando ese mismo Markdown tiene que convertirse en un EPUB que KDP acepte sin rebotarlo — y ahí es donde la mayoría de conversores genéricos se quedan cortos, porque el fichero que producen no es formalmente inválido para leerlo, pero sí lo es para publicarlo.

Por qué un Markdown a EPUB “genérico” falla en KDP

La forma más común de convertir Markdown a EPUB es reutilizar la hoja de estilos que ya tienes pensada para imprenta, quitándole @page y los break-* a mano. El resultado técnicamente abre en un lector, pero KDP lo rechaza o lo renderiza mal, por motivos muy concretos:

• Unidades de imprenta que un EPUB reflowable no entiende. Márgenes y tamaños en px o pt, o colores en var(--...), funcionan en Puppeteer pero no se resuelven en un lector EPUB — el dc:* del fichero queda con valores que ningún reader interpreta igual.
• position: fixed, @media print y overflow son reglas de página impresa. En un EPUB no hay “página” fija que recorrer: cada lector repagina el texto a su propio tamaño de fuente, y esas reglas simplemente no tienen dónde aplicarse.
• Código y URLs largas que no envuelven. Sin white-space: pre-wrap y overflow-wrap: break-word, una línea de código o un enlace sin espacios se sale del margen — es el error “This text is outside the margins” que KDP marca en su revisor.
• Un <hr> que desaparece. En imprenta, un separador de sección se resuelve con un salto de página; heredar esa regla tal cual en el EPUB deja un elemento de altura cero, que KDP reporta como “non-printable markup” y el lector pierde el separador.
• Metadatos vacíos. Un EPUB con dc:description vacío no es solo poco prolijo — es el error de validación RSC-005, y hace que el fichero sea formalmente inválido para epubcheck, no solo “mejorable”.

Markfolio no deriva el EPUB de la hoja de imprenta: aplica una hoja reflowable propia, que hereda de la plantilla solo la identidad visual (color primario, familia tipográfica) y resuelve la maquetación con las reglas de arriba ya corregidas.

Convertir tu Markdown a EPUB, paso a paso

1. Sube tu manuscrito. En el asistente Crear libro, elige “Ya tengo manuscrito” y sube tu .md (o .docx — pasa por el mismo pipeline de conversión, así que el resultado es idéntico).
2. Elige una plantilla. Para documentación o manuales, la plantilla Technical Book aplica una maquetación pensada para bloques de código y guías paso a paso. Puedes cambiar de plantilla más adelante sin perder tu configuración.
3. Selecciona el formato de salida. En la sección “Exportar y archivos KDP” tienes tres botones: PDF, EPUB o Ambos. Si necesitas también el interior de imprenta para la edición en tapa blanda, Ambos genera los dos formatos en paralelo desde el mismo archivo.
4. Fija el idioma del libro. El selector de idioma no es un detalle menor del EPUB: es el mismo valor que usa KDP para catalogar la tapa blanda, y el que se escribe en el dc:language del fichero. Si lo dejas sin elegir, el EPUB cae al inglés por defecto — no al idioma real de tu manuscrito.
5. Rellena los detalles del EPUB. Con EPUB o Ambos seleccionado aparece el panel “Detalles del EPUB”: título, autor y una descripción opcional (hasta 500 caracteres). Si no rellenas nada, Markfolio usa el nombre del archivo como título y deja el resto vacío sin invalidar el fichero.
6. Genera y descarga. El botón cambia de texto según el formato elegido (“Generar EPUB” o “Generar PDF + EPUB”) y descarga el archivo directamente desde el navegador — sin instalar Pandoc, Calibre ni ningún conversor aparte.

Qué valida Markfolio antes de dejarte descargar el EPUB

Comprobación	Qué hace
Estructura	Extrae una tabla de contenidos navegable de tus headings h1–h3. Si no detecta ninguno, genera el EPUB igual y te avisa de que la tabla de contenidos quedará vacía.
Imágenes	Las embebe en base64 dentro del propio fichero — no dependen de una ruta externa que se pueda romper.
Validez	El fichero resultante es EPUB 3.0 y pasa epubcheck sin errores; se prueba contra Calibre y Apple Books como lectores objetivo.
Velocidad	Menos de 5 segundos para manuscritos de hasta 50 páginas; el modo Ambos (PDF + EPUB) no pasa de 35 segundos en total.
Fallos parciales	Si el PDF falla pero el EPUB se genera bien, te entrega igualmente el EPUB descargable y marca el error del PDF por separado — un fallo no bloquea el otro formato.

Preguntas frecuentes

¿Necesito instalar Pandoc o Calibre para convertir Markdown a EPUB? No. Todo el proceso corre en el navegador — Markfolio genera el EPUB en memoria, sin escribir a disco ni depender de software instalado en tu máquina.

¿El EPUB que genera Markfolio sirve para subir directo a KDP? Sí. Es un EPUB 3.0 válido según epubcheck, que es el formato que KDP acepta directamente como manuscrito de ebook — no hace falta pasarlo por ninguna conversión adicional.

¿Qué pasa si mi Markdown no tiene headings (títulos de sección)? El EPUB se genera igual, pero la tabla de contenidos queda vacía y Markfolio te avisa antes de que lo descargues. Añadir #, ## o ### a tus secciones antes de exportar resuelve la tabla de contenidos.

¿Puedo generar el PDF de imprenta y el EPUB del mismo archivo a la vez? Sí, con el formato Ambos: se generan en paralelo y se descargan de forma secuencial, primero el PDF y luego el EPUB, sin tener que repetir el proceso ni mantener dos archivos fuente sincronizados.

¿Cambia algo si mi manuscrito es un .docx en vez de Markdown? No en el resultado final. El .docx pasa por el mismo pipeline de conversión que el Markdown antes de llegar al generador de EPUB, así que ambos orígenes producen el mismo tipo de fichero validado.

Si además quieres comparar esto con el flujo de Kindle Create, ya hicimos esa comparación criterio por criterio.