Jonathan
Geramos um EPUB de teste, rodamos o EPUBCheck e a resposta foi: zero erros, zero avisos. Depois tiramos o texto alternativo de uma imagem, regeramos, e rodamos de novo. A resposta foi a mesma: zero erros, zero avisos.
O validador oficial não reclama de imagem sem texto alternativo. Quem confia só nele publica um livro digital que leitor de tela não consegue descrever. Este artigo mostra o comando para gerar o EPUB com o Pandoc e o que o EPUBCheck pega e não pega. Mostra também uma armadilha mais perigosa: regenerar um livro a partir de uma fonte velha.
O Pandoc já tem uma explicação mais geral em Pandoc, o conversor universal. Aqui o foco é o uso dentro da produção de um livro.
O que é um EPUB por dentro
Um EPUB é um arquivo ZIP. Abrimos o do nosso teste. A estrutura tinha: o arquivo mimetype, o arquivo de manifesto content.opf, o sumário moderno nav.xhtml, um arquivo xhtml por capítulo, uma folha de rosto, uma página de capa, uma folha de estilo e as imagens. Um detalhe de empacotamento importa: o mimetype precisa ser o primeiro arquivo e estar sem compressão, senão o EPUB quebra. No teste, o Pandoc fez isso certo sozinho (Stored, 0% de compressão).
O comando
Os metadados vão em um arquivo YAML:
title: Livro de teste
subtitle: Um EPUB de verificação
author: Autor de Teste
lang: pt-BR
publisher: Editora de Teste
rights: © Autor de Teste
date: "2026"
identifier:
- scheme: ISBN
text: "978-65-000000-00-0"E o EPUB sai de uma linha:
pandoc livro.md -o livro.epub --metadata-file=meta.yaml \
--epub-cover-image=capa.jpg --css=estilo.css \
--toc --toc-depth=2 --split-level=1Conferimos as opções na ajuda do Pandoc que usamos: --metadata-file (metadados), --epub-cover-image (capa), --css (visual), --toc e --toc-depth (sumário), --split-level (em que nível o livro se parte em capítulos) e --epub-embed-font (fontes embutidas). A saída padrão é EPUB 3, e -t epub2 gera o formato antigo para quem exigir.
No nosso teste, o EPUB gerado tinha 7.274 bytes. O content.opf trouxe título, idioma pt-BR, autor, editora, direitos, data e o identificador. A folha de rosto saiu com título, subtítulo, autor, editora, data e direitos. As notas de rodapé viraram uma seção de notas com ligação de ida e volta.
O EPUBCheck
O EPUBCheck é o validador oficial do consórcio da web. Rodamos o do nosso servidor, que valida contra as regras do EPUB 3.3:
epubcheck livro.epubA saída esperada de um livro pronto:
Validating using EPUB version 3.3 rules.
No errors or warnings detected.
Messages: 0 fatals / 0 errors / 0 warnings / 0 infosA meta é zero. Fatais e erros impedem a publicação, e aviso também deve ser lido: alguns são aceitáveis, mas o ideal é zero.
Estragando de propósito
Um validador também precisa ser testado. Fizemos duas mutações.
Capa em PNG com nome de JPEG. Salvamos uma imagem PNG como capa-falsa.jpg e a usamos como capa. O EPUBCheck reprovou com OPF-029 ("o arquivo não parece corresponder ao tipo de mídia declarado") e avisou com PKG-022 ("o arquivo é PNG mas tem extensão jpg"). Um erro e um aviso.
Imagem sem texto alternativo. Trocamos  por . O Pandoc gerou <img src="../media/file0.jpg" />, sem o atributo alt. O EPUBCheck não reclamou de nada.
Por isso, a conferência de texto alternativo é nossa. Este comando lista as imagens sem o atributo:
unzip -p livro.epub "EPUB/text/*.xhtml" | grep -o "<img[^>]*>" | grep -v "alt="No livro certo, ele não imprime nada. No livro sem texto alternativo, imprimiu a linha da imagem. Se o seu EPUB é para leitor de tela, o texto alternativo precisa descrever a imagem. Imagem puramente decorativa pode levar alt vazio, e isso é uma decisão sua, e não um esquecimento.
O que o Pandoc não faz sozinho
Duas coisas do nosso pipeline original, aprendidas na prática:
- A página de créditos. Não existe opção do Pandoc para ela. No nosso caso, é uma página pronta que é reposta dentro do pacote, entre a folha de rosto e o primeiro capítulo. Sem repor, o livro sai sem créditos. Se você a reinserir mexendo no ZIP, mantenha o
mimetypecomo o primeiro arquivo e sem compressão. - A identidade do livro. Mantenha o mesmo identificador (
dc:identifier) entre versões de um livro. É ele que preserva a identidade da obra para os leitores que já a têm.
A fonte certa
Esta é a armadilha mais cara. Em um dos nossos livros, sobrou uma pasta de trabalho que parecia ser a fonte do EPUB. O texto dela era de uma versão antiga, e estava defasado. Não tinha um caso que entrou em uma revisão posterior. E ainda tinha uma história que foi removida por ser fabricada. Regenerar dali publicaria um livro velho, sem nenhum erro.
A prova é barata. Antes de confiar em qualquer arquivo de texto, conte com grep -c uma palavra que só existe na versão nova e outra que só existe na velha:
grep -c "palavra-so-da-versao-nova" fonte.md # deve ser maior que zero
grep -c "palavra-so-da-versao-velha" fonte.md # deve ser zeroA fonte correta, no nosso caso, era o dump do EPUB já publicado, convertido de volta para texto. As imagens vieram do EPUB de referência, e não da pasta de trabalho, porque as de lá eram anteriores a um reprocessamento.
Passo a passo
- Escolha a fonte certa e prove com as duas contagens.
- Escreva os metadados no YAML, com idioma
pt-BRe o ISBN do formato digital. - Gere com o Pandoc, com capa, CSS e sumário.
- Valide com o EPUBCheck: zero fatais, zero erros.
- Cheque o texto alternativo com o comando acima.
- Abra no Kindle Previewer, gratuito, e olhe cortes de palavra, tabelas que estouram e imagens sem respiro.
- Só então publique.
O erro que custa caro
Confiar no verde do validador. O EPUBCheck mede se o arquivo está bem formado, e não se o livro está certo. O texto alternativo ausente passa, a fonte velha passa, e um erro de revisão passa.
Quando NÃO usar
Para um livro com layout fixo, como um álbum ilustrado em que cada página é uma peça, o EPUB reflowable não é o formato certo. E para um livro que só existe impresso, o EPUB não é necessário. O EPUB é reflowable: o texto se adapta à tela, ao contrário do PDF.
Alternativa sem o nosso ambiente
O Pandoc é livre e roda em Linux, macOS e Windows. O EPUBCheck é um arquivo .jar que precisa de Java. Existem outros editores de EPUB, e o EPUBCheck valida o resultado de qualquer um. Nada aqui depende da nossa conta ou do nosso servidor.
O que o Claude faz hoje, e como fazer sem ele
Hoje o Claude monta o arquivo de texto a partir da versão aprovada, roda o Pandoc e o EPUBCheck e confere o texto alternativo. Sem ele, os comandos deste artigo fazem tudo isso.
Onde entra na operação
O EPUB é o passo 16 do procedimento, depois do miolo, e a base da amostra pública do livro. Para o que muda quando o destino é a Amazon, veja Kindle e KDP. O guia da esteira está em Como produzimos o miolo de um livro profissional sem InDesign.
Baixe, para guardar: mapa da esteira de 17 passos, com e sem IA (PDF).
Versões usadas neste artigo: veja a matriz de versões.
