epub2md

O que epub2md faz?

Converta um EPUB em Markdown, com agrupamento de capítulos baseado no sumário (TOC) e no spine.

Quando usar esta skill

Use esta skill quando o usuário:

• Fornecer um arquivo EPUB (.epub) e solicitar sua conversão para Markdown.
• Pedir o texto de um ebook como um único arquivo Markdown, ou como um arquivo Markdown por capítulo.
• Quiser dividir um EPUB em capítulos para processamento downstream (indexação, embeddings, tradução, revisão).
• Solicitar a inspeção da estrutura de um EPUB (spine, TOC, capítulos).

Não use esta skill para PDFs, documentos do Word ou páginas da web. Use ferramentas específicas para cada formato.

Entradas

• Um caminho de arquivo EPUB.
• Diretório de saída opcional (padrão: ./output).
• Modo opcional: single, chapters ou both (padrão: both).
• Agrupamento opcional: toc, spine ou auto (padrão: auto).

Saídas

Sempre produzidos (no diretório de saída):

• book-extracted/ — conteúdo EPUB bruto descompactado.
• book-assets/ — imagens e mídias referenciadas pelo livro.
• chapters/NN-slug.md — um arquivo Markdown por capítulo.
• chapters.json — manifesto dos capítulos com título, arquivos de origem, âncoras, caminho de saída.
• combined.html — capítulos concatenados para inspeção.
• book.md — o livro completo como um único arquivo Markdown.
• metadata.json — título, autores, idioma, identificador, editora, versão do EPUB, número de capítulos.

Como executar

A skill inclui um executor em scripts/run.sh que localiza a CLI epub2md e encaminha todos os argumentos. Funciona independentemente de o epub2md estar instalado:

1. Se epub2md estiver no PATH, ele é usado diretamente.
2. Caso contrário, se o pacote Python epub2md for importável, é usado python3 -m epub2md.
3. Caso contrário, o executor recorre à árvore de fonte ao lado dele (scripts/epub2md/), permitindo que a skill funcione a partir de um clone novo sem nenhuma etapa de instalação.

bash scripts/run.sh caminho/para/livro.epub -o output/ --overwrite

Preferível para uso repetido: instale o pacote uma vez.

pip install .
epub2md caminho/para/livro.epub -o output/ --overwrite

Para conversão de alta fidelidade, instale o Pandoc. O epub2md usa o Pandoc quando ele está disponível no PATH e recai para um conversor Python puro caso contrário.

Receitas comuns

Converter para um único arquivo Markdown

bash scripts/run.sh livro.epub -o out/ --mode single --overwrite
# lê: out/book.md

Dividir por capítulo usando o sumário (TOC)

bash scripts/run.sh livro.epub -o out/ --mode chapters --group-by toc --overwrite
# lê: out/chapters/NN-slug.md e out/chapters.json

Forçar agrupamento baseado no spine

Use quando o sumário (TOC) estiver ausente, malformado ou enganoso.

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

Usar como biblioteca Python

from epub2md import convert

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

Lógica de agrupamento

• Se existir um sumário (TOC), o modo padrão auto o utiliza. Cada entrada de nível superior do sumário se torna um capítulo. O capítulo inclui todos os documentos do spine desde o arquivo inicial da entrada até o arquivo inicial da próxima entrada. Isso reúne capítulos que estão divididos em vários arquivos XHTML.
• Se o sumário (TOC) estiver ausente, a ferramenta recai para o spine. Cada documento do spine se torna um capítulo.
• O material de front matter que aparece no spine antes da primeira entrada do sumário é agrupado como um capítulo "Front matter".

Tratamento de erros

• container.xml ou OPF ausente: a ferramenta termina com uma mensagem clara; o EPUB é inválido.
• Fragmentos XHTML malformados: analisados em modo leniente. Quando a conversão de um fragmento falha, o HTML bruto é incorporado em um bloco com delimitação, para que nenhum conteúdo seja perdido.
• Imagens referenciadas ausentes: aviso e manutenção do src original na saída Markdown.
• Pandoc não instalado: a ferramenta recai silenciosamente para markdownify no modo automático.

Referências

• references/spec.md — especificação completa, algoritmo de agrupamento e layout de saída.
• references/troubleshooting.md — soluções práticas para problemas comuns de conversão de EPUB.