redasadki/epub2md

Que fait epub2md ?

Convertit un EPUB en Markdown, avec une table des matières et un regroupement des chapitres basé sur la structure spine.

Quand utiliser cette compétence

Utilisez cette compétence lorsque l'utilisateur :

• Fournit un fichier EPUB (.epub) et demande sa conversion en Markdown.
• Demande le texte d'un ebook sous forme d'un seul fichier Markdown, ou d'un fichier Markdown par chapitre.
• Souhaite fractionner un EPUB par chapitre pour un traitement en aval (indexation, plongement, traduction, révision).
• Demande à inspecter la structure d'un EPUB (spine, TOC, chapitres).

N'utilisez pas cette compétence pour les PDF, les documents Word ou les pages web. Utilisez des outils spécifiques à ces formats.

Entrées

• Un chemin de fichier EPUB.
• Répertoire de sortie optionnel (par défaut : ./output).
• Mode optionnel : single, chapters ou both (par défaut : both).
• Regroupement optionnel : toc, spine ou auto (par défaut : auto).

Sorties

Toujours produites (dans le répertoire de sortie) :

• book-extracted/ — contenu brut décompressé de l'EPUB.
• book-assets/ — images et médias référencés par le livre.
• chapters/NN-slug.md — un fichier Markdown par chapitre.
• chapters.json — manifeste des chapitres avec titre, fichiers sources, ancres, chemin de sortie.
• combined.html — chapitres concaténés pour inspection.
• book.md — le livre complet sous forme d'un seul fichier Markdown.
• metadata.json — titre, auteurs, langue, identifiant, éditeur, version EPUB, nombre de chapitres.

Comment exécuter

La compétence fournit un lanceur dans scripts/run.sh qui trouve la CLI epub2md et transmet tous les arguments. Il fonctionne que epub2md soit installé ou non :

1. Si epub2md est dans le PATH, il est utilisé directement.
2. Sinon, si le package Python epub2md est importable, python3 -m epub2md est utilisé.
3. Sinon, le lanceur utilise l'arborescence source située à côté de lui (scripts/epub2md/), de sorte que la compétence fonctionne directement à partir d'un clone frais sans étape d'installation.

bash scripts/run.sh chemin/vers/livre.epub -o output/ --overwrite

Pour une utilisation répétée, il est préférable d'installer le package une fois.

pip install .
epub2md chemin/vers/livre.epub -o output/ --overwrite

Pour une conversion haute fidélité, installez Pandoc. epub2md utilise Pandoc lorsqu'il est disponible dans le PATH et revient sinon à un convertisseur purement Python.

Recettes courantes

Convertir en un seul fichier Markdown

bash scripts/run.sh livre.epub -o out/ --mode single --overwrite
# lit : out/book.md

Fractionner par chapitre en utilisant la TOC

bash scripts/run.sh livre.epub -o out/ --mode chapters --group-by toc --overwrite
# lit : out/chapters/NN-slug.md et out/chapters.json

Forcer le regroupement basé sur le spine

À utiliser lorsque la TOC est absente, malformée ou trompeuse.

bash scripts/run.sh livre.epub -o out/ --group-by spine --overwrite

Utiliser comme bibliothèque Python

from epub2md import convert

result = convert("livre.epub", output_dir="out", mode="both", overwrite=True)
print(result.book_md)
print(len(result.chapters))

Logique de regroupement

• Si une TOC existe, le mode par défaut auto l'utilise. Chaque entrée de premier niveau de la TOC devient un chapitre. Le chapitre inclut chaque document du spine depuis le fichier de début de l'entrée jusqu'au fichier de début de l'entrée suivante. Cela reconstitue les chapitres divisés en plusieurs fichiers XHTML.
• Si la TOC est absente, l'outil utilise le spine. Chaque document du spine devient un chapitre.
• Les pages de garde (front matter) apparaissant dans le spine avant la première entrée de la TOC sont regroupées en un seul chapitre "Pages de garde".

Gestion des erreurs

• Absence de container.xml ou d'OPF : l'outil se termine avec un message clair ; l'EPUB est invalide.
• Fragments XHTML mal formés : analysés en mode indulgent. Lorsque la conversion échoue pour un fragment, le HTML brut est intégré dans un bloc de code délimité afin qu'aucun contenu ne soit perdu.
• Images manquantes : un avertissement est émis et l'attribut src d'origine est conservé dans la sortie Markdown.
• Pandoc non installé : l'outil revient silencieusement à markdownify en mode auto.

Références

• references/spec.md — spécification complète, algorithme de regroupement et disposition des sorties.
• references/troubleshooting.md — correctifs pratiques pour les problèmes courants de conversion EPUB.