Como validar seu EPUB antes de publicar (epubcheck)

Onde rodar o EPUBCheck: no computador ou no navegador?

Rode no computador quando o livro não pode sair da máquina ou quando vai ser validado várias vezes seguidas. A versão atual e os requisitos estão no verbete EPUBCheck. Baixe o ZIP na página de instalação do EPUBCheck no W3C (w3.org/publishing/epubcheck/docs/installation/) ou na página de releases do GitHub (github.com/w3c/epubcheck/releases). O ZIP traz o epubcheck.jar e a pasta lib/, que precisam ficar juntos. Como não há atualizador embutido, atualizar é baixar o ZIP novo. O guia sobre como fazer o e-book mostra onde esta etapa entra no caminho todo.

No Windows, descompacte o ZIP numa pasta de caminho curto, como c:\epubcheck, sem separar o .jar da pasta lib/. Abra o Prompt de Comando (o PowerShell também serve), entre na pasta do livro com cd c:\epubs e rode o comando com o caminho do .jar.

java -jar c:\epubcheck\epubcheck.jar livro.epub

No macOS o gerenciador de pacotes instala com brew install epubcheck, e no Ubuntu e no Debian com apt-get install epubcheck, e a partir daí basta epubcheck livro.epub; esses pacotes são mantidos por voluntários, não pelo W3C. Se o EPUB ainda é uma pasta descompactada, use --mode exp pasta/, e --save empacota depois. Para guardar o relatório, --json saida.json grava em JSON, -o saida.xml em XML e -x saida.xmp em XMP.

Para validar no navegador, duas opções que o W3C lista são o epubcheck.net e o epubcheck-standalone, uma compilação experimental que roda no navegador sem enviar o arquivo. O epubcheck.net, da Data Mountain, aceita até 4 GB, guarda o EPUB em armazenamento temporário e devolve um relatório com erro, aviso e dica. No Brasil, a Simplíssimo, empresa de conversão de e-books, mantém um formulário que recebe o .epub de até 30 MB e manda o resultado por e-mail, sem mostrá-lo na tela.

Quem prefere janela a linha de comando tem o Pagina EPUB-Checker, interface gráfica gratuita, e há plugins do EPUBCheck para o Sigil e o Calibre, feitos por "Doitsu" e distribuídos no fórum MobileRead. O plugin do Sigil aparece no índice de plugins como um invólucro simples do EPUBCheck.

Um Fatal na primeira linha da saída diz que o EPUBCheck nem chegou ao livro: PKG-018 quer dizer que o arquivo EPUB não foi encontrado (confira o caminho digitado no comando), e PKG-004, que o cabeçalho do ZIP está corrompido (gere o EPUB de novo).

Como ler o relatório do EPUBCheck?

Cada mensagem traz quatro partes: a severidade, o código, o local e o texto. Um exemplo publicado pelo DAISY Consortium, que mantém o EPUBCheck, é ERROR(RSC-005): accessible_epub_3.epub/EPUB/ch01.xhtml(98,5): Error while parsing file: element "p" not allowed here; expected the element end-tag: severidade ERROR, código RSC-005, o arquivo ch01.xhtml na linha 98, coluna 5, e o texto, que diz o que está errado, um parágrafo onde se esperava o fechamento de uma tag. Um local -1,-1 quer dizer que o erro não tem posição específica.

A severidade decide o que fazer primeiro. Fatal impede o EPUBCheck de continuar; Error fere um requisito obrigatório da especificação; Warning é um desvio de prática recomendada; Info e Usage são informação. Comece por Fatal e Error e trate o Warning em seguida, sem pular: no Kindle Previewer, segundo o manual de publicação da Amazon, aviso também impede o livro de ficar disponível, como mostra o guia sobre como fazer o e-book. Para o EPUBCheck cobrar o mesmo rigor, a opção --failonwarnings faz o aviso contar como falha.

A tabela junta códigos do catálogo oficial ligados ao contêiner, aos nomes de arquivo, às referências internas, ao OPF, ao XHTML e à navegação. Ela vale para a versão atual: o próprio W3C avisa que a lista de mensagens é trabalho em andamento e deve ser refeita.

Como corrigir e validar de novo até zerar?

Abra o EPUB num editor que mostra o código dos arquivos, como o Sigil, e vá ao arquivo e à linha que a mensagem aponta. Corrija na ordem da severidade e valide de novo a cada rodada: um erro de marcação pode causar muitos outros, e corrigi-lo pode fazer os demais sumirem, e por isso a DAISY recomenda revalidar com frequência, para não gastar tempo procurando problema que já foi resolvido.

O caso real que mostra a leitura é o de um usuário do Sigil 0.9.2, que em 20/01/2016 abriu uma issue no GitHub do programa. Ele inseriu o autor pelo editor de metadados e o EPUBCheck devolveu duas mensagens ERROR RSC-005 /OEBPS/content.opf, uma na linha 9, coluna 28, e outra na linha 13, coluna 35: o atributo role e o atributo event "not allowed here". O texto da mesma mensagem já diz o que o arquivo devia ter: expected attribute "id", "ns:file-as", "ns:role" or "xml:lang", ou seja, o atributo com prefixo. O código diz que é um erro de análise, o arquivo é o content.opf, e a linha e a coluna dizem onde abrir; sem ler essas partes, o autor só saberia que "deu erro no autor".

Nem toda recusa vem do EPUBCheck: a distribuidora ou a loja pode devolver o próprio aviso, com a correção feita fora do validador. A Bookwire Brasil, distribuidora de livros digitais, lista os cinco erros que mais travam a validação dos livros que recebe: capa interna com menos de 600 px de largura, ISBN com hífens ou espaços, UUID incorreto, e-book sem autor e e-book sem capa declarada. Para o autor faltando, o roteiro da Bookwire, publicado sem data, é abrir o Sigil, apertar F8, escolher "Add Metadata" e então Creator ou Author; para a capa, o menu Tools e depois Add Cover.

A Simplíssimo publicou em 09/03/2021 mensagens reais de recusa com a correção no Sigil, como ERROR_EBOOK_AUTHOR_MISSING e ERROR_EPUB_COVER_META_MISSING. Esses códigos não seguem o formato do EPUBCheck, de três letras, hífen e número, como RSC-005: vêm do sistema que recebeu o arquivo (leitura nossa).

Fim da rodada: rode o comando de novo. O arquivo passa no EPUBCheck quando a saída mostra 0 fatals / 0 errors; com os avisos também zerados, ela diz No errors or warnings detected e 0 fatals / 0 errors / 0 warnings / 0 infos, o rigor a buscar se o livro vai para a Amazon.

E se o arquivo passar no EPUBCheck e a loja recusar mesmo assim?

O EPUBCheck confere estrutura, pacote, marcação e referências internas, não o texto, e o Kindle Previewer é o exame à parte da Amazon; o guia sobre como fazer o e-book explica a diferença entre os dois. No catálogo de mensagens lido em 29/09/2026, as únicas de acessibilidade são a ACC-009, de MathML sem alttext, e a ACC-011, de link SVG sem título, ambas de severidade Usage; não há código para imagem sem texto alternativo, e o manual da Amazon diz que problema de acessibilidade, como imagem sem texto alternativo, pode levar à supressão do livro.

Para a Amazon, o Kindle Previewer atual é o 4: a Amazon diz que a versão 3 e as anteriores não têm mais suporte, e ele abre .epub, .kpf, .docx e outros formatos. O KPF, arquivo gerado no Kindle Create, é o caso que foge do EPUBCheck; o guia sobre formatos de e-book explica a escolha.

No fim, o que está na tela é a saída do EPUBCheck com 0 fatals / 0 errors e, rodado com --json livro.json, o relatório gravado ao lado do EPUB; se o destino é a Amazon, o mesmo arquivo aberto no Kindle Previewer 4 sem erro nem aviso.