epub2md

¿Qué hace epub2md?

Convierte un EPUB a Markdown, con agrupación de capítulos basada en el TOC y el spine.

Cuándo usar esta habilidad

Usa esta habilidad cuando el usuario:

• Proporciona un archivo EPUB (.epub) y solicita convertirlo a Markdown.
• Pide el texto de un libro electrónico como un solo archivo Markdown, o como un archivo Markdown por capítulo.
• Quiere dividir un EPUB por capítulos para procesamiento posterior (indexación, embeddings, traducción, revisión).
• Solicita inspeccionar la estructura de un EPUB (spine, TOC, capítulos).

No uses esta habilidad para PDFs, documentos de Word o páginas web. Usa herramientas específicas para cada formato.

Entradas

• Una ruta de archivo EPUB.
• Directorio de salida opcional (por defecto: ./output).
• Modo opcional: single (único), chapters (capítulos) o both (ambos) (por defecto: both).
• Agrupación opcional: toc, spine, o auto (por defecto: auto).

Salidas

Siempre se producen (en el directorio de salida):

• book-extracted/ — contenido EPUB sin comprimir.
• book-assets/ — imágenes y medios referenciados por el libro.
• chapters/NN-slug.md — un archivo Markdown por capítulo.
• chapters.json — manifiesto de capítulos con título, archivos fuente, anclas, ruta de salida.
• combined.html — capítulos concatenados para inspección.
• book.md — el libro completo como un solo archivo Markdown.
• metadata.json — título, autores, idioma, identificador, editorial, versión EPUB, número de capítulos.

Cómo ejecutar

La habilidad incluye un ejecutor en scripts/run.sh que encuentra la CLI de epub2md y reenvía todos los argumentos. Funciona tanto si epub2md está instalado como si no:

1. Si epub2md está en el PATH, se usa directamente.
2. De lo contrario, si el paquete Python epub2md es importable, se usa python3 -m epub2md.
3. De lo contrario, el ejecutor recurre al árbol fuente junto a él (scripts/epub2md/), por lo que la habilidad funciona desde un clon nuevo sin necesidad de instalación.

bash scripts/run.sh ruta/al/libro.epub -o salida/ --overwrite

Para uso repetido, se recomienda instalar el paquete una vez.

pip install .
epub2md ruta/al/libro.epub -o salida/ --overwrite

Para una conversión de alta fidelidad, instala Pandoc. epub2md usa Pandoc cuando está disponible en el PATH y recurre a un conversor Python puro en caso contrario.

Recetas comunes

Convertir a un solo archivo Markdown

bash scripts/run.sh libro.epub -o salida/ --mode single --overwrite
# leer de: salida/book.md

Dividir por capítulos usando el TOC

bash scripts/run.sh libro.epub -o salida/ --mode chapters --group-by toc --overwrite
# leer de: salida/chapters/NN-slug.md y salida/chapters.json

Forzar agrupación basada en el spine

Úsalo cuando el TOC falte, esté malformado o sea engañoso.

bash scripts/run.sh libro.epub -o salida/ --group-by spine --overwrite

Usar como biblioteca Python

from epub2md import convert

resultado = convert("libro.epub", output_dir="salida", mode="both", overwrite=True)
print(resultado.book_md)
print(len(resultado.chapters))

Lógica de agrupación

• Si existe un TOC, el modo auto (por defecto) lo usa. Cada entrada de nivel superior del TOC se convierte en un capítulo. El capítulo incluye todos los documentos del spine desde el archivo inicial de la entrada hasta el archivo inicial de la siguiente entrada. Esto reensambla capítulos que están divididos en múltiples archivos XHTML.
• Si falta el TOC, la herramienta recurre al spine. Cada documento del spine se convierte en un capítulo.
• El material preliminar que aparece en el spine antes de la primera entrada del TOC se agrupa como un capítulo "Material preliminar".

Manejo de errores

• Falta container.xml o OPF: la herramienta termina con un mensaje claro; el EPUB no es válido.
• Fragmentos XHTML malformados: se analizan en modo permisivo. Cuando falla la conversión de un fragmento, el HTML sin procesar se incrusta en un bloque de código, por lo que no se pierde contenido.
• Imágenes referenciadas faltantes: se emite una advertencia y se conserva el src original en la salida Markdown.
• Pandoc no instalado: la herramienta recurre silenciosamente a markdownify en modo automático.

Referencias

• references/spec.md — especificación completa, algoritmo de agrupación y diseño de salida.
• references/troubleshooting.md — soluciones prácticas para problemas comunes de conversión de EPUB.