25  Solução de problemas

Problemas que já aconteceram nos livros da casa, com a causa e o conserto. A mensagem citada é a que aparece no terminal ou no registro do workflow.

25.1 unresolved crossref

O texto usa uma referência cruzada (@sec-…, @fig-…, @tbl-…) cujo identificador não existe. Confira o identificador no heading, na figura ou na legenda da tabela; lembre que ele diferencia maiúsculas e não aceita acentos.

25.2 citeproc: reference not found

Uma citação usa uma chave que não está no .bib. O validador rápido acusa o mesmo problema antes do render, com o arquivo e a linha. Confira a grafia da chave; se a obra é nova, recupere os metadados e crie a entrada (Capítulo 14).

25.3 O validador acusa uma citação que não existe

Um @ seguido de texto fora de bloco de código é lido como citação, inclusive dentro de código inline. Exemplos de sintaxe de citação vão em blocos de código delimitados por três crases, que o validador ignora. Endereços de e-mail e URLs com @ não são afetados.

25.4 Um subtítulo “Referências” vazio aparece no fim de cada capítulo

A opção reference-section-title está definida em _quarto.yml. Remova-a: a lista de referências vive em references.qmd, que já tem o próprio título.

25.5 O workflow constrói mas não publica

Em Settings → Pages → Build and deployment, a origem não está configurada como GitHub Actions. Configure e dispare o workflow de novo na aba Actions.

25.6 O workflow não rodou depois do push

O gatilho só dispara para alterações em .qmd, .bib, .scss, .css, .yml e code/. Alterar apenas imagens não republica; dispare o workflow à mão.

25.7 O livro no ar está diferente do local

O site publicado é gerado a partir do repositório, não do _book/ local. Confira se a alteração foi enviada (git status, git log origin/main) e se o workflow terminou.

25.8 A capa saiu cortada na base

No modo --headless=new do Chrome, --window-size pode incluir a moldura da janela e cortar os últimos pixels da página. Use o binário headless_shell do Chromium (variável CHROME do script) ou confira o resultado com o tamanho esperado de 1600 × 2500 px.

25.9 Fontes não carregam

Os arquivos .woff2 precisam estar em fonts/ e ser referenciados por styles.css com caminho relativo. Se o livro está num subcaminho do domínio (/apostila/), o Quarto ajusta os caminhos; não use barras iniciais nas regras font-face.

25.10 pip install falha ao instalar o validador

Crie o ambiente virtual com o Python indicado no CLAUDE.md do livro e instale com pip install -r code/requirements.txt. As versões dos pacotes são fixadas de propósito.

25.11 Um PDF entrou no repositório

Apagar no commit seguinte não basta: o arquivo continua no histórico. Remova-o do histórico (o autor já precisou fazê-lo com amend e force push) e confira se o .gitignore cobre o padrão que deixou o arquivo passar.