11  GitHub Pages

Você chegou ao último capítulo deste manual. Ao longo da jornada, aprendeu a usar o Terminal, instalar ferramentas com gerenciadores de pacotes, entendeu os conceitos do Git, configurou seu ambiente, e descobriu diferentes formas de trabalhar com controle de versão — pelo Terminal, pelo GitHub Desktop ou pelo Positron.

Agora vem a recompensa: colocar seu trabalho no ar. Neste capítulo, você vai aprender a usar o GitHub Pages, um serviço gratuito do GitHub que transforma repositórios em sites na internet. Sem servidor para configurar, sem hospedagem para pagar, sem complicação.

11.1 O que é GitHub Pages?

O GitHub Pages é um serviço de hospedagem de sites estáticos oferecido gratuitamente pelo GitHub. Ele pega os arquivos do seu repositório — HTML, CSS, JavaScript, imagens — e publica em uma URL pública, acessível por qualquer pessoa no mundo.

“Site estático” significa que as páginas são arquivos prontos, sem processamento no servidor. Diferente de um site dinâmico (como WordPress ou um sistema de e-commerce), onde cada página é gerada no momento do acesso, um site estático é simplesmente um conjunto de arquivos que o navegador baixa e exibe.

Isso pode parecer limitado, mas é perfeito para:

  • Documentação de projetos
  • Portfólios pessoais
  • Blogs
  • Materiais didáticos
  • Livros e manuais (como este que você está lendo!)
  • Currículos online
  • Landing pages

Ferramentas como Quarto, Jekyll, Hugo e MkDocs geram sites estáticos sofisticados a partir de arquivos simples em Markdown. Você escreve em texto puro, executa um comando, e tem um site completo pronto para publicar.

11.2 Como funciona?

O fluxo é simples:

  1. Você cria um repositório no GitHub com os arquivos do seu site
  2. Você ativa o GitHub Pages nas configurações do repositório
  3. O GitHub publica os arquivos em uma URL como seu-usuario.github.io/nome-do-repositorio
  4. Toda vez que você faz push de alterações, o site é atualizado automaticamente

Não há etapa de “deploy” manual, não há servidor para gerenciar. O GitHub cuida de tudo.

11.3 Opções de publicação

O GitHub Pages permite definir de onde vêm os arquivos do site. A forma mais prática para livros Quarto é usar a pasta /docs na branch principal.

11.4 A pasta /docs

Nessa configuração, os arquivos do site ficam dentro de uma pasta chamada docs/ na branch principal (main). O restante do repositório pode conter código-fonte, dados ou outros arquivos que não fazem parte do site publicado.

Essa é a opção ideal para livros Quarto porque permite uma separação clara: os arquivos .qmd ficam na raiz do projeto, enquanto o site gerado (HTML, CSS, imagens) vai para a pasta docs/. Assim, você mantém organização sem precisar de configurações avançadas.

Para usar essa opção, basta configurar no _quarto.yml:

project:
  type: book
  output-dir: docs

Depois, nas configurações do repositório no GitHub, selecione a pasta /docs como fonte do GitHub Pages.

11.5 Outras opções

Existem outras formas de configurar o GitHub Pages, como usar a raiz do repositório ou uma branch separada chamada gh-pages. Essas alternativas envolvem fluxos de trabalho diferentes ou automação com GitHub Actions e não serão tratadas em detalhes neste manual.

11.6 Publicando um site Quarto: passo a passo

Vamos ao processo completo para publicar um livro ou site feito com Quarto.

11.6.1 Passo 1: Configure o Quarto para gerar na pasta docs

No arquivo _quarto.yml do seu projeto, defina o diretório de saída:

project:
  type: book
  output-dir: docs

Isso faz com que o comando quarto render gere todos os arquivos HTML dentro da pasta docs/.

11.6.2 Passo 2: Renderize o projeto

No Terminal (ou no terminal integrado do Positron), execute:

quarto render

O Quarto processará todos os arquivos .qmd e gerará o site na pasta docs/.

11.6.3 Passo 3: Faça a sincronização do seu repositório local com o repositório remoto no github

11.6.4 Passo 5: Ative o GitHub Pages

  1. No repositório do GitHub, clique em Settings (ícone de engrenagem)
  2. No menu lateral esquerdo, clique em Pages
  3. Em Source, selecione Deploy from a branch
  4. Em Branch, selecione main e a pasta /docs
  5. Clique em Save

11.6.5 Passo 6: Aguarde e acesse

O GitHub levará alguns minutos para publicar o site. Você pode acompanhar o progresso na seção Actions do repositório.

Quando estiver pronto, o site estará disponível em:

https://seu-usuario.github.io/nome-do-repositorio/
DicaEncontrando a URL

Após ativar o GitHub Pages, a URL do site aparece na própria página de configurações (Settings → Pages), no topo da seção.

11.7 Atualizando o site

Depois da configuração inicial, atualizar o site é simples:

  1. Edite seus arquivos .qmd
  2. Execute quarto render para regenerar o site
  3. Faça commit e push:
git add .
git commit -m "Atualiza conteúdo"
git push

O GitHub Pages detecta automaticamente as alterações na pasta docs/ e republica o site. Em poucos minutos, as mudanças estarão no ar.

11.8 Domínio personalizado

Por padrão, seu site terá uma URL como seu-usuario.github.io/repositorio. Mas você pode configurar um domínio próprio, como www.seusite.com.br.

11.8.1 Como configurar

  1. Compre um domínio em um registrador (Registro.br, GoDaddy, Namecheap, etc.)

  2. No GitHub, vá em Settings → Pages e digite seu domínio em Custom domain

  3. No seu registrador de domínio, configure os registros DNS:

    • Para domínio raiz (exemplo.com): crie registros A apontando para os IPs do GitHub:

      185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

    • Para subdomínio (www.exemplo.com): crie um registro CNAME apontando para seu-usuario.github.io

  4. Aguarde a propagação DNS (pode levar até 24 horas)

  5. Marque a opção Enforce HTTPS para ter conexão segura

NotaHTTPS gratuito

O GitHub Pages oferece certificado HTTPS gratuito, mesmo para domínios personalizados. Isso significa que seu site terá o cadeado de segurança no navegador sem custo adicional.

11.9 Arquivo .nojekyll

Por padrão, o GitHub Pages processa os arquivos com Jekyll (um gerador de sites estáticos). Se você usa Quarto ou outro gerador, pode haver conflitos — especialmente com pastas que começam com underscore (_), que o Jekyll ignora.

Para desativar o processamento Jekyll, crie um arquivo vazio chamado .nojekyll na pasta docs/:

touch docs/.nojekyll

O Quarto geralmente cria esse arquivo automaticamente, mas é bom verificar se ele existe.

11.10 Solucionando problemas comuns

11.10.1 O site não aparece

  • Verifique se a pasta docs/ existe e contém um arquivo index.html
  • Confirme que você fez push após o quarto render
  • Aguarde alguns minutos — a primeira publicação pode demorar
  • Verifique a aba Actions no GitHub para ver se há erros

11.10.2 Erro 404 (página não encontrada)

  • Verifique se a configuração do GitHub Pages está apontando para a pasta correta (/docs)
  • Confirme que o arquivo index.html está na raiz da pasta docs/
  • Se estiver usando caminhos relativos, verifique se estão corretos

11.10.3 Estilos ou imagens não carregam

  • Verifique se o _quarto.yml tem a configuração correta de output-dir
  • Confirme que a pasta docs/ contém as subpastas de estilos e imagens
  • Limpe o cache do navegador e tente novamente

11.10.4 Alterações não aparecem no site

  • Confirme que você executou quarto render após editar os arquivos
  • Verifique se fez commit e push
  • Aguarde alguns minutos para o GitHub processar
  • Verifique a aba Actions para confirmar que o deploy foi concluído

11.11 Alternativas ao GitHub Pages

Embora o GitHub Pages seja excelente para a maioria dos casos, existem alternativas:

Netlify
Oferece mais recursos, como formulários, funções serverless e deploy automático de branches. Também é gratuito para projetos pessoais.
Vercel
Focado em frameworks JavaScript modernos, mas funciona bem com sites estáticos. Gratuito para uso pessoal.
Cloudflare Pages
Boa performance global e generoso plano gratuito.
Quarto Pub
Serviço da própria Posit para publicar documentos Quarto. Simples de usar com o comando quarto publish.

Para a maioria dos usuários acadêmicos e projetos pessoais, o GitHub Pages é mais que suficiente — e tem a vantagem de manter tudo no mesmo lugar que seu código.

11.12 Exemplos de sites no GitHub Pages

Para inspiração, alguns exemplos de sites hospedados no GitHub Pages:

  • R for Data Science (r4ds.hadley.nz) — livro completo sobre R
  • Happy Git with R (happygitwithr.com) — guia de Git para usuários de R
  • Quarto documentation (quarto.org) — documentação oficial do Quarto
  • Este manual — sim, este manual que você está lendo!

Todos são projetos de código aberto. Você pode visitar os repositórios, ver como são organizados e aprender com eles.

11.13 Conclusão

O GitHub Pages fecha o ciclo completo: você escreve, versiona com Git, colabora pelo GitHub, e publica para o mundo — tudo de graça, tudo integrado.

Para acadêmicos, é uma ferramenta transformadora. Materiais didáticos que antes ficavam trancados em pastas ou sistemas fechados agora podem estar acessíveis a qualquer pessoa com um navegador. Pesquisas, tutoriais, livros, portfólios — tudo pode ser compartilhado de forma aberta e profissional.

Você começou este manual aprendendo a navegar pelo Terminal. Agora termina sabendo publicar um site na internet. Esse é o poder de dominar suas ferramentas.

DicaPróximos passos

Agora que você conhece Git, GitHub e GitHub Pages, que tal:

  1. Criar um site pessoal com seu portfólio ou currículo?
  2. Publicar os documentos de estudo de uma disciplina que você ensina ou estuda?
  3. Transformar sua dissertação ou tese em um livro online?
  4. Contribuir para um projeto open source que você admira?