20  Publicando

O livro é publicado pelo GitHub Pages (GitHub, Inc., 2026), e quem o constrói é um workflow do GitHub Actions que roda a cada envio ao ramo main. O Quarto documenta três maneiras de publicar no Pages (Posit Software, PBC, 2026); a casa usa a que não depende da máquina do autor: o site é renderizado no servidor do GitHub, a partir do que está no repositório.

20.1 Configuração única

Uma vez por repositório, em Settings → Pages → Build and deployment, a origem deve ser GitHub Actions. Sem isso o workflow constrói o site e falha ao publicá-lo. Como o GitHub Pages do autor usa domínio próprio, o livro fica em henriquealvarenga.com/<repositório>/.

20.2 O workflow

O arquivo .github/workflows/publish.yml define três trabalhos encadeados:

flowchart LR
  V[validate-bib<br>validate_bib.py + deep_validate_bib.py] --> B[build<br>quarto render --to html]
  B --> D[deploy<br>GitHub Pages]
Figura 20.1: Os três trabalhos do workflow de publicação.
  1. validate-bib instala o Python fixado, os pacotes de code/requirements.txt, e roda a validação rápida (que bloqueia) e a profunda (que gera relatório sem bloquear). Os relatórios ficam disponíveis como artefato por 30 dias.
  2. build instala a versão fixada do Quarto, renderiza o HTML, lista a saída e a empacota como artefato do Pages. O cache de _freeze e .quarto acelera renders repetidos.
  3. deploy publica o artefato no ambiente github-pages e mostra a URL na aba Actions.

Em pull requests só o primeiro trabalho roda; nada é publicado. O workflow também pode ser disparado à mão na aba Actions (workflow_dispatch).

20.3 Quando o workflow roda

O gatilho é um envio ao main que altere arquivos .qmd, .bib, .scss, .css, .yml ou a pasta code/. Alterar só uma imagem, portanto, não republica o livro; nesse caso, dispare o workflow à mão.

20.4 Versões fixadas

O workflow fixa a versão do Quarto (hoje 1.10.18) e do Python (3.13). Fixar evita que uma atualização do serviço mude o livro sem que ninguém tenha mexido nele. A regra da casa é que a versão do Quarto no workflow acompanhe a instalada localmente: quando uma sobe, a outra sobe junto.

20.5 Quando falha

A aba Actions do repositório mostra cada execução e o registro de cada passo. Os motivos mais comuns, em ordem:

  • a validação rápida encontrou uma chave órfã ou um campo faltando (o registro diz qual);
  • o render acusou uma referência cruzada não resolvida ou um YAML malformado;
  • a origem do Pages não está configurada como GitHub Actions.

A solução de problemas detalha cada caso.

NotaPontos-chave
  • O site é construído no GitHub, a partir do repositório; a origem do Pages deve ser GitHub Actions.
  • Três trabalhos: validar a bibliografia, renderizar, publicar; pull requests só validam.
  • O gatilho é um envio ao main que altere texto, bibliografia, estilo ou configuração.
  • Versões do Quarto e do Python são fixadas e acompanham a máquina do autor.