🎯 Objetivos de aprendizagem¶

Ao final deste capítulo você será capaz de:

• Navegar, criar pastas e ler arquivos pelo terminal (pwd, ls, cd, mkdir, cat, code .) em Linux, macOS e Windows, sabendo qual shell está usando.
• Configurar o VS Code com as extensões recomendadas nesta trilha e um settings.json que formata o código ao salvar.
• Usar as abas Elements, Console, Network e Lighthouse do DevTools, e o modo de dispositivo, para inspecionar qualquer página da Web.
• Instalar o Node.js LTS por um gerenciador de versões (nvm no Linux/macOS, nvm-windows no Windows) e explicar por que isso é melhor do que o instalador comum.
• Ler um package.json e usar npm init, npm install, npm run e npx com segurança.
• Conferir versões (node -v, npm -v, git --version, npm ls) e diagnosticar um ambiente quebrado.
• Padronizar indentação, codificação e fim de linha em qualquer editor com um .editorconfig.

📋 Pré-requisitos¶

• [ ] Um computador em que você possa instalar programas (Linux, macOS ou Windows 10/11).
• [ ] Cerca de 2 GB livres em disco e acesso à internet.
• [ ] Uma conta de e-mail que você acesse — vai servir para o GitHub no Capítulo 02.

Este é o primeiro capítulo da trilha Deploy & Ferramentas; não há capítulo anterior para retomar. Se você está no Nível 1, faça-o antes ou junto com a Aula 02 — tudo aqui usa só HTML, CSS e o navegador. Se está no Nível 2 ou 3, use-o como revisão do ambiente: é comum descobrir que o node -v da máquina é de dois anos atrás. Hoje você monta a bancada de trabalho; no Capítulo 02, aprende a guardar o histórico dela com Git.

🗺️ Roteiro¶

1. Por que uma caixa de ferramentas¶

Um site é só um conjunto de arquivos de texto. Dá para escrever HTML no Bloco de Notas e abrir com dois cliques — e nas primeiras aulas do Nível 1 isso basta. O problema aparece na terceira semana: você tem cinco páginas, uma pasta de imagens, um CSS que não recarrega, um colega que quer ver o site na máquina dele e, no fim do semestre, precisa publicar tudo em um endereço público.

Cada ferramenta deste capítulo resolve uma dor específica:

Você não precisa dominar tudo hoje. Precisa instalar tudo hoje, entender para que serve cada peça e saber onde conferir se está funcionando. É o que a maioria dos "não roda na minha máquina" do semestre tem em comum: uma peça faltando na bancada.

🧠 Você sabia? O bash, terminal padrão da maioria das distribuições Linux, é mais velho que a Web. Foi escrito por Brian Fox para o projeto GNU, e o nome é um trocadilho: Bourne Again SHell, em homenagem ao sh de Stephen Bourne, que ele substituiu. Os comandos ls, cd e cat que você vai usar hoje são os mesmos que um programador usava em um terminal de texto verde décadas antes de existir navegador.

2. O terminal¶

2.1 Qual terminal usar¶

O terminal é um programa que recebe comandos digitados e mostra o resultado em texto. O que interpreta os comandos se chama shell, e há vários. Para que os comandos deste material funcionem iguais em todas as máquinas, a recomendação é:

No Windows existe também o PowerShell, que aceita ls, cd, pwd, cat e mkdir como apelidos de comandos próprios — mas sem as opções do Linux (ls -la dá erro lá) e sem touch. Para não ter dois conjuntos de comandos na cabeça, use o Git Bash ao longo de toda esta trilha. Você instala o Git for Windows no passo a passo deste capítulo e ganha os dois de uma vez: o git e um shell compatível com Linux.

💡 Dica Quem usa Windows e quer um Linux "de verdade" dentro do Windows pode instalar o WSL (wsl --install em um PowerShell como administrador). Não é obrigatório para nada do WebLab; o Git Bash resolve tudo do que precisamos.

Para descobrir qual shell está rodando:

echo $SHELL

Saída típica: /bin/bash (Linux, Git Bash) ou /bin/zsh (macOS).

2.2 Onde estou, o que tem aqui, para onde vou¶

Todo terminal está sempre "dentro" de uma pasta, chamada diretório de trabalho. Três comandos resolvem 80 % da navegação:

pwd          # print working directory: mostra em que pasta você está
ls           # lista o conteúdo da pasta atual
cd Documentos  # change directory: entra na pasta Documentos

Variações de ls que você vai usar todo dia:

ls -l        # formato longo: permissões, dono, tamanho, data de cada item
ls -a        # inclui arquivos ocultos (os que começam com ponto, como .gitignore)
ls -la       # os dois juntos — o mais usado
ls css       # lista o conteúdo de uma subpasta sem entrar nela

Variações de cd:

cd ..        # sobe um nível (para a pasta "pai")
cd ../..     # sobe dois níveis
cd ~         # vai para a sua pasta pessoal (home)
cd           # o mesmo que cd ~
cd -         # volta para a pasta em que você estava antes
cd /         # vai para a raiz do sistema de arquivos

🔬 Investigue Abra o terminal e rode pwd, depois ls -la. Quantos itens começam com ponto? Eles não aparecem no gerenciador de arquivos comum — são configurações de programas (.bashrc, .config, .ssh). Agora rode cd / e ls: você está vendo a raiz do sistema. Volte com cd -. Em nenhum momento você "quebrou" nada: navegar é só olhar.

2.3 Criando e lendo arquivos¶

mkdir projetos               # cria a pasta projetos
mkdir -p projetos/site/css   # cria a cadeia inteira de pastas de uma vez (-p = parents)
touch index.html             # cria um arquivo vazio (ou atualiza a data de um existente)
cat index.html               # mostra o conteúdo de um arquivo de texto na tela
cp index.html contato.html   # copia
mv contato.html paginas/     # move (ou renomeia, se o destino for um nome de arquivo)
rm rascunho.html             # apaga um arquivo — sem lixeira, sem desfazer
rm -r pasta-velha            # apaga uma pasta e tudo dentro dela — cuidado dobrado
clear                        # limpa a tela (ou Ctrl+L)

E o comando que você mais vai digitar neste semestre:

code .

Abre o VS Code com a pasta atual como projeto. O ponto significa "aqui". Abrir a pasta (e não um arquivo solto) é o que faz o Live Server, o Git e as extensões entenderem onde o projeto começa.

⚠️ Atenção rm não pergunta e não tem lixeira. rm -rf com o caminho errado apaga pastas inteiras em silêncio. Antes de qualquer rm -r, rode ls no alvo para ter certeza do que vai sumir. E nunca copie um comando com rm -rf da internet sem entender cada parte dele.

2.4 Caminhos absolutos e relativos¶

Um caminho absoluto começa na raiz e não depende de onde você está: /home/ana/projetos/site/index.html (Linux), /Users/ana/projetos/site/index.html (macOS), C:\Users\ana\projetos\site\index.html (Windows — no Git Bash aparece como /c/Users/ana/…).

Um caminho relativo parte do diretório de trabalho: se você está em projetos/site, então css/estilo.css é o arquivo dentro da subpasta css, e ../outro-site é a pasta irmã.

Essa distinção volta com força no Capítulo 03: um href="/css/estilo.css" (absoluto, começa com barra) funciona no seu computador e quebra quando o site é publicado em um subcaminho como usuario.github.io/site-evento/. Guarde a ideia: barra no início = "a partir da raiz".

2.5 Truques que economizam horas¶

• Tab completa nomes de arquivos e pastas. Digite cd Doc e aperte Tab: vira cd Documentos/. Dois Tab mostram as opções quando há mais de uma.
• ↑ e ↓ percorrem o histórico de comandos. history lista tudo.
• Ctrl+C interrompe o programa em execução (é assim que você para um servidor de desenvolvimento).
• Ctrl+R busca no histórico: digite parte de um comando antigo e ele aparece.
• Arraste uma pasta do gerenciador de arquivos para a janela do terminal: o caminho absoluto dela é colado.
• Nomes com espaço precisam de aspas ou barra invertida: cd "Meus Projetos" ou cd Meus\ Projetos. Melhor ainda: não use espaços nem acentos em nomes de pastas de projeto. site-evento, não Site do Evento.

3. VS Code¶

3.1 Instalação e o comando code¶

Baixe em https://code.visualstudio.com e instale. Três detalhes por sistema:

• Windows: no instalador, marque "Add to PATH" e as opções "Open with Code" no menu de contexto. Sem o PATH, code . não funciona no terminal.
• macOS: abra o VS Code, aperte Cmd+Shift+P e execute Shell Command: Install 'code' command in PATH. Só assim code . funciona no Terminal.
• Linux: o pacote .deb/.rpm já registra o comando. Em distribuições com Snap, sudo snap install code --classic.

Teste:

code --version

A saída tem três linhas: a versão, um hash do build e a arquitetura (x64 ou arm64).

3.2 Extensões recomendadas¶

Extensões são instaladas pela aba Extensions (Ctrl+Shift+X) ou pelo terminal, o que é mais rápido e reproduzível. O identificador de cada uma é editor.nome:

Instalação de todas de uma vez:

code --install-extension ritwickdey.LiveServer
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension Vue.volar
code --install-extension humao.rest-client
code --install-extension eamodio.gitlens
code --install-extension EditorConfig.EditorConfig

Para conferir o que está instalado:

code --list-extensions

💡 Dica Prefere o VS Code em português? Instale MS-CEINTL.vscode-language-pack-pt-BR. Este material usa os nomes em inglês dos menus e abas (Settings, Extensions, Elements) porque é assim que aparecem na documentação oficial e nas respostas do Stack Overflow — vale a pena se acostumar com eles.

3.3 settings.json¶

As configurações do VS Code vivem em um arquivo JSON. Abra-o com Ctrl+Shift+P → Preferences: Open User Settings (JSON). Cole (ou mescle) isto:

settings.json (configurações do usuário)

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.wordWrap": "on",
  "editor.linkedEditing": true,
  "editor.bracketPairColorization.enabled": true,
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "emmet.variables": { "lang": "pt-BR" },
  "liveServer.settings.donotShowInfoMsg": true,
  "terminal.integrated.defaultProfile.windows": "Git Bash",
  "[markdown]": { "files.trimTrailingWhitespace": false }
}

O que cada linha faz:

• editor.formatOnSave + editor.defaultFormatter: ao salvar, o Prettier reorganiza indentação, aspas e quebras de linha. Você para de gastar atenção com estética e passa a gastar com lógica.
• editor.tabSize: 2 + insertSpaces: dois espaços por nível, o padrão do ecossistema JavaScript/Vue.
• editor.linkedEditing: renomear a tag de abertura de um elemento HTML renomeia a de fechamento junto.
• files.eol: "\n": fim de linha no padrão Unix. Evita o aviso LF will be replaced by CRLF do Git no Windows.
• emmet.variables.lang: o atalho ! do Emmet passa a gerar <html lang="pt-BR"> em vez de en.
• terminal.integrated.defaultProfile.windows: o terminal integrado do VS Code no Windows abre o Git Bash, não o PowerShell.

Há também configurações por projeto, em .vscode/settings.json dentro da pasta do projeto. Elas valem só ali e podem ser versionadas — útil para uma equipe usar o mesmo formatador.

3.4 Prettier: .prettierrc¶

O Prettier tem opiniões fortes e poucas opções. As que mudamos no WebLab ficam em um arquivo na raiz do projeto, e o estilo bate com o código que você vê nas aulas (sem ponto e vírgula, aspas simples):

.prettierrc

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "es5"
}

Sem esse arquivo, o Prettier usa os padrões dele (com ponto e vírgula e aspas duplas). Nenhum dos dois estilos é "errado" — o que importa é o projeto inteiro seguir um só.

3.5 .editorconfig¶

O .prettierrc fala com o Prettier; o .editorconfig fala com qualquer editor (VS Code, Sublime, IntelliJ, Vim). Ele define o básico da forma do arquivo — indentação, codificação, fim de linha — e é lido pela extensão EditorConfig. Coloque na raiz de todo projeto:

.editorconfig

# Configuração lida por qualquer editor com suporte a EditorConfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

root = true diz "pare de procurar .editorconfig nas pastas acima". A seção [*] vale para todo arquivo; a [*.md] abre uma exceção para Markdown, em que dois espaços no fim da linha significam quebra de linha.

3.6 Atalhos essenciais¶

No macOS, troque Ctrl por Cmd e Alt por Option.

3.7 Emmet: HTML em uma linha¶

O VS Code traz o Emmet embutido: você digita uma abreviação e aperta Tab. Em um arquivo .html:

• ! → esqueleto completo (<!DOCTYPE html>, <html lang="pt-BR">, <meta viewport>, <title>).
• ul>li*3 → uma lista com três itens.
• .card>h2+p → uma div.card com um h2 e um p dentro.
• a[href="contato.html"]{Contato} → um link com atributo e texto.
• table>tr*3>td*2 → uma tabela 3×2.

Vale a pena passar dez minutos no cheat sheet oficial (https://docs.emmet.io/cheat-sheet/); as páginas do site do evento saem em metade do tempo.

4. DevTools: o raio-X do navegador¶

Todo navegador moderno traz ferramentas de desenvolvedor. Abra com F12, Ctrl+Shift+I ou botão direito → Inspecionar (no macOS, Cmd+Option+I). Os exemplos aqui são do Chrome; o Firefox tem as mesmas abas com nomes quase iguais.

4.1 Elements — o HTML como o navegador entendeu¶

A aba Elements mostra a árvore DOM: não o seu arquivo, mas o que o navegador construiu a partir dele (com tags que ele fechou por você, com o que o JavaScript inseriu). Ao clicar em um elemento:

• O painel Styles lista cada regra CSS que atinge o elemento, em ordem de prioridade, com as sobrescritas riscadas. É onde você descobre por que "meu CSS não aplica": outra regra mais específica venceu, ou o seletor não bate.
• Você pode editar valores ao vivo (clique em 16px e digite 24px) para experimentar sem tocar no arquivo. Nada disso é salvo — é rascunho.
• O painel Computed mostra o valor final de cada propriedade e o diagrama de caixa (margin, border, padding, conteúdo).
• A lupa no canto superior esquerdo (Ctrl+Shift+C) seleciona um elemento clicando na página.

4.2 Console — o que o JavaScript tem a dizer¶

A aba Console mostra mensagens de console.log, avisos e erros em vermelho com o arquivo e a linha (script.js:12). Também é um interpretador: digite document.title e aperte Enter; digite 2 + 2; digite document.querySelectorAll('a').length para contar os links da página. Nas aulas de JavaScript do Nível 1 você vai passar mais tempo aqui do que no editor.

4.3 Network — cada arquivo que a página pediu¶

A aba Network grava tudo o que o navegador baixou: HTML, CSS, imagens, fontes, scripts, chamadas a APIs. Para cada requisição: Status (200 ok, 404 não encontrado, 304 não mudou), Type, Size e Time. A linha do tempo à direita (o waterfall) mostra o que esperou por quem.

Três hábitos:

1. Abra o DevTools antes de recarregar (F5), senão a aba fica vazia.
2. Marque Disable cache enquanto desenvolve, para sempre ver a versão nova do CSS.
3. Use o seletor de velocidade (No throttling → Slow 4G) para sentir o site como quem está no 4G ruim do interior.

Na barra de baixo, o resumo: número de requisições, total transferido, tempo até DOMContentLoaded e até Load.

4.4 Device toolbar — o site no celular¶

Ctrl+Shift+M liga o modo de dispositivo: a página é renderizada nas dimensões de um celular ou tablet, com toque simulado. Escolha um aparelho na lista ou digite largura e altura. É a ferramenta central da aula de telas responsivas do Nível 1 — mas lembre que é uma simulação: fontes, desempenho e o teclado virtual só se veem em um celular de verdade.

4.5 Lighthouse — a nota do seu site¶

A aba Lighthouse roda uma auditoria automática e dá notas de 0 a 100 em quatro categorias: Performance, Accessibility, Best Practices e SEO. Escolha Mobile, clique em Analyze page load e espere um minuto. Cada item reprovado vem com explicação e link. É o critério objetivo de "site bom" usado nos checkpoints das trilhas: ≥ 90 em Performance e Accessibility.

4.6 Sources e Application — para depois¶

Sources permite colocar pontos de parada (breakpoints) no JavaScript e executar linha a linha — você vai usar nas aulas de funções e eventos. Application mostra localStorage, cookies e service workers — aparece no Nível 3, quando o UniEventos guarda inscrições no navegador.

🔬 Investigue Abra https://weblab.aprendabit.com com a aba Network aberta e Disable cache marcado. Recarregue. Anote: quantas requisições? Qual o maior arquivo (clique no cabeçalho Size para ordenar)? Quanto tempo até DOMContentLoaded? Agora mude para Slow 4G e recarregue de novo. O que mais demorou? Esse é o tipo de medição que você vai repetir no seu próprio site publicado, no Capítulo 03.

5. Node.js e npm¶

5.1 Por que um dev front-end precisa de Node¶

O Node.js roda JavaScript fora do navegador. Você só vai escrever servidores com ele no Nível 2 — mas precisa dele desde já porque as ferramentas do ofício são escritas em JavaScript: o Prettier que formata seu CSS, o ESLint que aponta erros, o Vite que empacota o Vue, o serve que sobe um servidor local. Todas são instaladas e executadas pelo npm, o gerenciador de pacotes que vem junto com o Node.

Pense no npm como uma loja de aplicativos para código: qualquer pessoa publica um pacote (uma pasta com JavaScript e um package.json), e qualquer projeto instala esse pacote com um comando. O registro público tem milhões de pacotes, do minúsculo ao gigantesco.

🧠 Você sabia? Um pacote chamado left-pad, com 11 linhas que só adicionavam espaços à esquerda de um texto, era dependência indireta de milhares de projetos. Quando o autor o removeu do npm em uma disputa, builds do mundo inteiro quebraram na mesma tarde — e o npm mudou as regras para impedir a remoção de pacotes publicados. É a lição de que todo npm install é um ato de confiança em desconhecidos; o package-lock.json, que você vai ver adiante, existe para tornar essa confiança pelo menos reproduzível.

5.2 LTS e o gerenciador de versões¶

O Node tem duas linhas: Current (versões ímpares, novidades primeiro, suporte curto) e LTS (Long Term Support — versões pares, recebem correções por anos). Use sempre a LTS: hoje, a linha 22 (a 24 também é LTS e funciona). O create-vue do Nível 3 exige ^22.18.0 || >=24.12.0, o que é mais um motivo para não ficar com um Node velho.

Há dois jeitos de instalar. O instalador de https://nodejs.org funciona, mas deixa uma versão única e fixa, e no Linux/macOS costuma exigir sudo para instalar pacotes globais. O jeito recomendado é um gerenciador de versões, que instala o Node na sua pasta pessoal (sem sudo) e permite ter várias versões lado a lado — o projeto antigo de um freela em Node 18, o projeto novo em Node 22.

Linux e macOS — nvm. Copie o comando de instalação da página oficial (https://github.com/nvm-sh/nvm#installing-and-updating); ele tem este formato, com a versão atual do nvm no meio da URL:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Feche e abra o terminal (o instalador acrescenta linhas ao ~/.bashrc ou ~/.zshrc, que só são lidas em um terminal novo). Depois:

nvm install --lts          # baixa e instala a LTS mais recente
nvm use --lts              # ativa nesta sessão
nvm alias default 'lts/*'  # torna a LTS o padrão de todo terminal novo
nvm ls                     # lista as versões instaladas (a ativa tem ->)
node -v                    # v22.x.x (ou v24.x.x)
npm -v                     # 10.x.x ou 11.x.x

Para uma versão específica: nvm install 22, nvm use 22.

Windows — nvm-windows. É um projeto diferente, com comandos parecidos. Baixe o nvm-setup.exe em https://github.com/coreybutler/nvm-windows/releases, instale e abra um Git Bash novo:

nvm install lts    # instala a LTS mais recente
nvm list           # mostra o número exato da versão instalada
nvm use lts        # ativa (pode pedir um terminal como administrador)
node -v
npm -v

Se preferir não usar gerenciador no Windows, o instalador oficial também serve: winget install OpenJS.NodeJS.LTS em um PowerShell, ou o .msi do site. Você perde a troca de versões, mas ganha simplicidade.

5.3 npm: os quatro comandos¶

Entre em uma pasta de projeto e:

npm init -y

Cria um package.json com valores padrão (o -y aceita todas as perguntas). Em seguida:

npm install prettier --save-dev   # instala um pacote como dependência de desenvolvimento
npm install                       # instala tudo que o package.json lista (ao clonar um projeto)
npm run formatar                  # executa o script "formatar" definido em package.json
npx prettier --check .            # executa um pacote sem instalar globalmente

• npm install <pacote> (ou npm i) baixa o pacote para node_modules/ e o registra em dependencies. Com -D (ou --save-dev), registra em devDependencies — coisas que só existem enquanto você desenvolve (formatador, empacotador, ferramentas de teste), e não no site final.
• npm install sem argumentos lê package.json e package-lock.json e recria node_modules/ inteira. É o primeiro comando que você roda ao baixar qualquer projeto Node.
• npm run <nome> executa um comando definido em scripts. npm run sem nome lista os scripts disponíveis.
• npx <comando> procura o executável em node_modules/.bin do projeto; se não existir, baixa uma cópia temporária e pergunta se pode executar. É assim que você usa npx create-vue@latest sem instalar nada antes.

5.4 package.json explicado¶

Depois de npm init -y, npm install -D prettier serve e a edição dos scripts, o arquivo de um projeto de teste fica assim (a ordem dos campos e um ou outro campo extra variam com a versão do npm):

package.json

{
  "name": "ola-weblab",
  "version": "1.0.0",
  "description": "Projeto de teste do ambiente WebLab",
  "scripts": {
    "dev": "serve . -l 3000",
    "formatar": "prettier --write .",
    "verificar": "prettier --check ."
  },
  "keywords": [],
  "author": "Seu Nome",
  "license": "MIT",
  "devDependencies": {
    "prettier": "^3.6.2",
    "serve": "^14.2.4"
  }
}

Campo a campo:

O ^ antes da versão é semver (versionamento semântico): ^3.6.2 aceita qualquer 3.x.y a partir de 3.6.2, mas não 4.0.0. O primeiro número muda quando há quebra de compatibilidade; o segundo, quando há funcionalidade nova; o terceiro, quando há correção.

🔎 Por baixo do capô Ao rodar npm install, o npm lê package.json, resolve a árvore de dependências (cada pacote depende de outros, que dependem de outros), baixa tudo do registro para node_modules/ e grava em package-lock.json a versão exata de cada pacote instalado. Os executáveis dos pacotes ganham um atalho em node_modules/.bin/ — é por isso que serve funciona dentro de scripts sem caminho: o npm coloca essa pasta no PATH enquanto roda um script. E é por isso que npx serve acha o serve do projeto antes de pensar em baixar qualquer coisa.

5.5 node_modules e package-lock.json¶

Duas regras que evitam metade dos problemas de Git do semestre:

1. node_modules/ nunca vai para o Git nem para o .zip. É regenerável com npm install, pesa dezenas ou centenas de megabytes e tem milhares de arquivos.
2. package-lock.json sempre vai para o Git. Ele garante que qualquer pessoa — um colega ou o servidor — instale exatamente as mesmas versões que você testou.

6. Gerenciando versões¶

Quando algo "não funciona", a primeira pergunta é: qual versão? Comandos de diagnóstico:

node -v              # versão do Node ativa
npm -v               # versão do npm
git --version        # versão do Git
nvm current          # qual Node o nvm ativou nesta sessão (Linux/macOS)
which node           # de onde o executável node está vindo
npm ls --depth=0     # pacotes instalados no projeto, sem as dependências das dependências
npm outdated         # o que tem versão nova disponível
npm view vite version  # última versão publicada de um pacote

Para fixar a versão do Node por projeto, crie um .nvmrc na raiz com o número da linha:

.nvmrc

22

Quem entrar na pasta e rodar nvm use recebe a versão certa sem pensar. Muitos projetos também declaram o mesmo em package.json, no campo engines:

{
  "engines": {
    "node": ">=22.18.0"
  }
}

⚠️ Atenção Se node -v mostra uma versão diferente da que você acabou de instalar com o nvm, há dois Nodes na máquina: um do instalador antigo, outro do nvm. which -a node lista todos. Desinstale o antigo (ou deixe nvm alias default decidir) para não passar o semestre com um ambiente que muda a cada terminal.

🚀 Passo a passo — Ambiente pronto e um projeto de teste no Live Server¶

Ao fim destes passos, sua máquina responde a node -v, npm -v e git --version, o VS Code tem as extensões recomendadas, e um projeto mínimo abre no navegador pelo Live Server e recarrega sozinho ao salvar. Faça na ordem; cada passo tem um jeito de conferir.

Passo 1 — Git (e o Git Bash, no Windows)¶

• Windows: baixe e instale o Git for Windows em https://git-scm.com/download/win (ou winget install --id Git.Git -e --source winget no PowerShell). Aceite os padrões; ele instala o Git Bash.
• macOS: no Terminal, git --version. Se não estiver instalado, o sistema oferece as Command Line Tools; aceite. Alternativa: brew install git.
• Linux (Ubuntu/Debian): sudo apt update && sudo apt install git.

Conferir (em um terminal novo):

git --version

Esperado: git version 2.x.y.

Passo 2 — VS Code e o comando code¶

Instale conforme a §3.1 e, em um terminal novo:

code --version

Esperado: três linhas, começando pela versão. No Windows, use o Git Bash; no macOS, só funciona depois do Shell Command: Install 'code' command in PATH.

Passo 3 — extensões¶

code --install-extension ritwickdey.LiveServer
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension Vue.volar
code --install-extension humao.rest-client
code --install-extension eamodio.gitlens
code --install-extension EditorConfig.EditorConfig
code --list-extensions

Esperado: a última linha lista as sete extensões.

Passo 4 — settings.json¶

No VS Code, Ctrl+Shift+P → Preferences: Open User Settings (JSON) → cole o conteúdo da §3.3 → salve. Se o arquivo já tinha conteúdo, mescle dentro das mesmas chaves { }.

Passo 5 — Node.js LTS¶

Siga a §5.2 para o seu sistema. Conferir, em um terminal novo:

node -v
npm -v
npx -v

Esperado: v22.x.x (ou v24.x.x), 10.x.x (ou 11.x.x) e o mesmo número do npm.

Passo 6 — a pasta de projetos e o projeto de teste¶

Crie uma pasta para todos os projetos do WebLab e, dentro dela, o projeto de teste:

mkdir -p ~/weblab/ola-weblab
cd ~/weblab/ola-weblab
mkdir css js
touch index.html css/estilo.css js/script.js
ls -R

Esperado:

.:
css  index.html  js

./css:
estilo.css

./js:
script.js

Abra no VS Code:

code .

Passo 7 — os três arquivos¶

index.html (digite ! e Tab para o esqueleto, depois complete)

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Olá, WebLab</title>
    <link rel="stylesheet" href="css/estilo.css" />
  </head>
  <body>
    <main>
      <h1>Ambiente pronto</h1>
      <p>Se esta página recarregou sozinha quando você salvou, o Live Server está funcionando.</p>
      <p id="relogio">Carregando o relógio pelo JavaScript…</p>
    </main>
    <script src="js/script.js"></script>
  </body>
</html>

css/estilo.css

/* Estilo mínimo só para provar que o CSS foi carregado */
body {
  font-family: system-ui, sans-serif;
  max-width: 40rem;
  margin: 2rem auto;
  padding: 0 1rem;
  background: #f5f5f0;
  color: #222;
}

h1 {
  color: #1b6b4a;
}

js/script.js

// Mostra a hora atual e prova que o JavaScript foi carregado
const relogio = document.querySelector('#relogio')

function atualizarRelogio() {
  const agora = new Date()
  relogio.textContent = `Agora são ${agora.toLocaleTimeString('pt-BR')}`
}

atualizarRelogio()
setInterval(atualizarRelogio, 1000)

console.log('Ambiente WebLab: JavaScript carregado com sucesso')

Passo 8 — Live Server¶

Com index.html aberto, clique em Go Live no canto inferior direito da janela (ou botão direito no arquivo → Open with Live Server). O navegador abre http://127.0.0.1:5500/index.html.

Mude o texto do <h1> e salve: a página recarrega sozinha. Abra o DevTools (F12) → Console: a mensagem Ambiente WebLab: JavaScript carregado com sucesso está lá. Aba Network, recarregue: quatro requisições (index.html, estilo.css, script.js e um favicon.ico com 404 — normal, ainda não há favicon; o Capítulo 03 resolve).

Passo 9 — npm init e os arquivos de padronização¶

No terminal integrado do VS Code (Ctrl+</kbd>), dentro deola-weblab`:

npm init -y
npm install -D prettier serve

Crie .prettierrc e .editorconfig com o conteúdo das §3.4 e §3.5, e acrescente os scripts ao package.json até ele ficar como na §5.4. Depois:

npm run formatar
npm run dev

Esperado: o Prettier lista os arquivos formatados; o serve sobe em http://localhost:3000 (é um segundo servidor local, sem recarga automática — serve para conferir que npm run funciona). Pare com Ctrl+C.

Como conferir¶

🧪 Laboratório¶

Nível A — Fixação¶

A1. Você está em ~/weblab/site-evento/css e roda cd .. e depois pwd. O que aparece? E se em seguida rodar cd ~ e pwd?

A2. Qual a diferença entre npm install prettier e npm install -D prettier? Em que campo do package.json cada um registra o pacote, e qual dos dois é o certo para um formatador?

A3. Preveja o que acontece ao rodar npx serve . em uma pasta que não tem o serve instalado nem localmente nem globalmente. O comando falha?

A4. Em uma pasta vazia, mkdir -p projetos/site/css cria quantas pastas? O que muda se projetos já existir? E o que acontece com mkdir projetos/site/css (sem -p) na pasta vazia?

A5. Para cada situação, diga qual aba do DevTools responde: (a) "por que o color: red não aplicou neste parágrafo?"; (b) "qual arquivo voltou com 404?"; (c) "o que meu console.log imprimiu?"; (d) "como o site fica em uma tela de 375 px?"; (e) "qual a nota de acessibilidade da página?".

A6. node -v e nvm current podem mostrar valores diferentes? Descreva uma situação em que isso acontece e como corrigir.

Nível B — Aplicação¶

B1. Estrutura em um comando. Crie, com um único mkdir e um único touch, a estrutura do site do evento: site-evento/index.html, programacao.html, inscricao.html, palestrantes.html, contato.html, css/estilo.css, js/script.js e a pasta img/ vazia. Mostre o resultado com ls -R.

Resultado esperado:

site-evento:
contato.html  css  img  index.html  inscricao.html  js  palestrantes.html  programacao.html

site-evento/css:
estilo.css

site-evento/img:

site-evento/js:
script.js

B2. Formatação automática. Crie js/bagunca.js com exatamente este conteúdo, salve e observe o que o Prettier faz:

const   produtos=[{nome:"Café",preco:5},{nome:"Pão de queijo",
preco:4}]
function total( lista ){let soma=0;for(const p of lista){soma+=p.preco};return soma}
console.log( total(produtos) );

Resultado esperado: ao salvar, o arquivo fica com dois espaços de indentação, aspas simples, sem ponto e vírgula, um item por linha no array e o for em várias linhas — sem você tocar em nada.

B3. Caçador de requisições. Com a aba Network aberta e Disable cache marcado, carregue a página inicial de três sites: https://weblab.aprendabit.com, o portal da sua universidade ou escola e um site de notícias à sua escolha. Para cada um, registre: número de requisições, total transferido, maior arquivo (nome e tamanho) e tempo até DOMContentLoaded. Repita com Slow 4G.

Resultado esperado: uma tabela com três linhas e as medições nas duas velocidades, mais uma frase por site dizendo qual recurso mais atrasou o carregamento no 4G lento.

B4. Scripts próprios. No projeto ola-weblab, acrescente ao package.json um script abrir que executa code ., e um script limpar que apaga node_modules (rm -rf node_modules). Rode npm run limpar, confira com ls -a que a pasta sumiu, e depois npm install para recriá-la.

Resultado esperado: npm run lista cinco scripts; depois de npm install, npm ls --depth=0 volta a mostrar prettier e serve com as mesmas versões de antes (é o package-lock.json garantindo isso).

Nível C — Desafio¶

C1. Gerador de projeto. Escreva um script novo-projeto.sh que receba um nome (bash novo-projeto.sh cardapio) e: recuse se a pasta já existir; crie a pasta com index.html (esqueleto completo com lang="pt-BR", viewport e título igual ao nome), css/estilo.css, js/script.js, .editorconfig e .prettierrc; e termine abrindo o VS Code na pasta. Torne-o executável e use-o para criar a pasta do seu projeto autoral.

🏆 Desafios¶

🐛 Erros comuns¶

🏠 Para praticar depois da aula (1 h)¶

Monte o ambiente completo e crie a pasta do seu projeto autoral (o site com o tema que você escolheu na sua trilha):

1. Siga o passo a passo até o fim; corrija qualquer item da tabela "Como conferir" que não bata.
2. Crie a pasta do projeto autoral em ~/weblab/<nome-do-projeto> (sem espaços nem acentos) com index.html, css/estilo.css, js/script.js, .editorconfig e .prettierrc. O index.html deve ter lang="pt-BR", viewport, um <title> com o nome do projeto e um <h1>.
3. Abra com o Live Server e deixe um console.log com o nome do projeto no script.js.
4. Tire três capturas de tela: (a) o terminal com a saída de node -v, npm -v e git --version; (b) o terminal com code --list-extensions; (c) o navegador com o site no Live Server e o DevTools aberto na aba Console mostrando a sua mensagem.

Critério de pronto: as três capturas mostram versões LTS do Node, as sete extensões e a mensagem no Console; a pasta do projeto tem os cinco arquivos e não contém node_modules.

Guarde: um .zip da pasta do projeto (sem node_modules) e as três capturas em um único PDF, num lugar seguro. A partir do Capítulo 02, isso vira o link do repositório no GitHub.

✅ Está no ar quando…¶

Nada vai ao ar neste capítulo — a bancada é que fica pronta. Confira:

• [ ] node -v imprime v22.x.x ou v24.x.x; npm -v imprime 10.x.x ou superior; git --version imprime 2.x.y.
• [ ] code . abre o VS Code na pasta atual, a partir do terminal recomendado para o seu sistema.
• [ ] code --list-extensions lista Live Server, Prettier, ESLint, Vue - Official, REST Client, GitLens e EditorConfig.
• [ ] Salvar um arquivo mal indentado o reformata (Prettier + formatOnSave).
• [ ] O Live Server serve o index.html em 127.0.0.1:5500 e recarrega ao salvar.
• [ ] Você encontra um console.log na aba Console e um 404 na aba Network sem ajuda.
• [ ] A pasta do projeto autoral existe, com .editorconfig e .prettierrc na raiz e sem node_modules no que será entregue.
• [ ] Você sabe explicar, em uma frase, a diferença entre npm install, npm run e npx.

📚 Para aprofundar¶

• VS Code — documentação oficial (introdução, terminal integrado, atalhos): https://code.visualstudio.com/docs
• VS Code — referência de atalhos em PDF (Linux, macOS, Windows): https://code.visualstudio.com/docs/configure/keybindings
• Emmet — cheat sheet oficial: https://docs.emmet.io/cheat-sheet/
• Chrome DevTools — guia oficial em português (Elements, Console, Network, Lighthouse): https://developer.chrome.com/docs/devtools?hl=pt-br
• Node.js — trilha "Aprenda" em português (o que é Node, como instalar, npm): https://nodejs.org/pt/learn
• nvm — instalação e uso: https://github.com/nvm-sh/nvm#installing-and-updating
• nvm-windows — releases e instruções: https://github.com/coreybutler/nvm-windows
• npm — documentação de package.json e dos comandos: https://docs.npmjs.com/cli/v10/configuring-npm/package-json
• Prettier — opções de configuração: https://prettier.io/docs/options
• EditorConfig — especificação e exemplos: https://editorconfig.org
• Pro Git (capítulo 1, "Começando", para chegar preparado ao Capítulo 02): https://git-scm.com/book/pt-br/v2

No próximo capítulo, a bancada ganha memória: Git para guardar cada versão do projeto e GitHub para publicá-lo, colaborar e abrir o seu primeiro pull request.

🎯 Objetivos de aprendizagem¶

Ao final deste capítulo você será capaz de:

• Explicar o que é um commit, o que ele guarda e por que o Git é diferente de uma pasta com cópias numeradas.
• Descrever as três áreas do Git (diretório de trabalho, área de preparação e repositório) e dizer em qual delas cada arquivo está, lendo a saída de git status.
• Criar branches, mesclar com git merge e resolver um conflito lendo os marcadores no arquivo.
• Criar um repositório local, registrar mudanças (git add, git commit) e navegar pelo histórico (git log, git diff, git show).
• Escrever um .gitignore, um README.md e um .gitattributes que servem para qualquer projeto das trilhas.
• Desfazer trabalho com segurança escolhendo entre git restore, git commit --amend, git reset e git revert.
• Autenticar-se no GitHub pelo terminal (gh auth login), criar o repositório remoto (gh repo create), publicar (git push) e abrir, revisar e mesclar um pull request (gh pr create, gh pr merge).
• Usar git stash, tags anotadas e um fluxo de trabalho em dupla sem sobrescrever o código do colega.

📋 Pré-requisitos¶

• [ ] Ambiente do Capítulo 01 pronto: git --version responde 2.x.y, code . abre o VS Code e você navega pelo terminal.
• [ ] A pasta ~/weblab/site-evento com as cinco páginas do site do evento acadêmico (Nível 1) — ou a pasta do seu projeto autoral, se você está em outra trilha.
• [ ] Um e-mail que você acesse, para criar a conta no GitHub.
• [ ] O gh (GitHub CLI) instalado — o Passo 4 do passo a passo mostra como, em cada sistema.

No Capítulo 01 você montou a bancada: terminal, VS Code, DevTools, Node e npm. A bancada funciona, mas não tem memória — apagou, apagou; quebrou, quebrou. Hoje você instala essa memória. O Git guarda cada versão do projeto na sua máquina; o GitHub guarda uma cópia na internet, permite trabalhar em dupla e é o endereço público do seu trabalho daqui em diante. No Capítulo 03, esse mesmo repositório vira um site publicado.

🗺️ Roteiro¶

1. Por que versionar¶

Abra a pasta de projetos antigos de qualquer colega e você encontra alguma variação disto:

site-final.zip   site-final-2.zip   site-final-agora-vai.zip
site-final-agora-vai-CORRIGIDO.zip   site-final-versao-do-joao.zip

Esse esquema falha em quatro pontos, e todos aparecem no semestre: não dá para saber o que mudou entre duas pastas sem abrir as duas e comparar arquivo por arquivo; não dá para desfazer só uma parte (se a versão nova quebrou o menu mas melhorou o rodapé, você perde as duas coisas ao voltar); não dá para trabalhar em dupla sem alguém sobrescrever o outro por WhatsApp; e não dá para publicar, porque nenhuma hospedagem moderna aceita .zip — todas leem um repositório Git.

Um sistema de controle de versão resolve os quatro. O Git registra o projeto inteiro em pontos no tempo (os commits), guarda quem fez cada mudança e por quê, permite voltar a qualquer ponto e permite que várias pessoas mexam nos mesmos arquivos e reconciliem o resultado.

E há um efeito colateral pedagógico que importa mais do que parece: quem versiona experimenta mais. Sem Git, você hesita antes de reescrever o CSS que está "quase bom". Com Git, você cria uma branch, destrói tudo, e volta ao estado anterior com um comando. A coragem para refatorar é uma consequência técnica do versionamento.

🧠 Você sabia? Linus Torvalds escreveu a primeira versão do Git em pouco mais de duas semanas, depois que o projeto do kernel Linux perdeu o direito de usar a ferramenta proprietária que vinha usando. O objetivo declarado era ser rápido, distribuído e à prova de corrupção de dados — por isso todo commit é identificado por um hash do próprio conteúdo. Mudou um byte em qualquer arquivo de qualquer commit antigo? O hash muda, e o Git percebe. Não é um recurso de segurança adicionado depois: é o formato de armazenamento.

2. Como o Git pensa¶

2.1 Snapshots, não diferenças¶

A maioria dos sistemas antigos guardava, para cada arquivo, a lista de diferenças em relação à versão anterior. O Git guarda fotografias do projeto inteiro (snapshots). A cada commit ele salva o estado de todos os arquivos rastreados; os que não mudaram não são copiados de novo, apenas referenciados.

Cada commit é um objeto com o conteúdo de todos os arquivos naquele instante, o autor, o e-mail e o instante da gravação, a mensagem que você escreveu e o hash do commit anterior (o "pai").

É esse último campo que forma a corrente: cada commit aponta para o anterior, e o histórico é a corrente inteira. O identificador de um commit é um hash de 40 caracteres hexadecimais, mas na prática você usa os 7 primeiros (a3f9c21), que já são únicos em um projeto de porte comum.

2.2 As três áreas¶

Este é o conceito que mais confunde no começo, e o que mais economiza tempo depois. Um arquivo do seu projeto vive em uma de três áreas:

  Diretório de trabalho          Área de preparação            Repositório
  (working tree)                 (staging area / index)        (.git)
  os arquivos que você           o que você escolheu para      o histórico
  edita no VS Code               entrar no próximo commit      permanente

        │ ─────── git add ──────────────► │ ──── git commit ───────► │
        │ ◄────── git restore ─────────── │                          │
        │ ◄──────────────── git restore --source=HEAD ─────────────  │

O diretório de trabalho é a pasta que você vê no gerenciador de arquivos; editar aqui não registra nada. A área de preparação é uma lista do que vai no próximo commit, e existe para você poder commitar parte do que fez — corrigir o menu em um commit e o rodapé em outro, mesmo tendo feito as duas coisas juntas. O repositório é a pasta oculta .git na raiz do projeto, onde os commits ficam: apagou a .git, apagou o histórico; copiou a .git junto, levou o histórico.

Um arquivo pode estar em quatro estados: não rastreado (o Git nunca o viu), modificado (mudou desde o último commit), preparado (está na área de preparação) e inalterado. O git status diz exatamente em qual estado está cada arquivo — leia-o sempre.

2.3 HEAD, branch e a linha do tempo¶

Uma branch é apenas um nome que aponta para um commit — não é uma cópia da pasta. HEAD é um ponteiro para a branch em que você está: git switch outra move o HEAD, e o Git troca o conteúdo da pasta para bater com aquele commit. Criar uma branch é instantâneo, porque só cria um nome; é por isso que o fluxo "uma branch por tarefa" é normal em qualquer time.

🔎 Por baixo do capô Entre em um repositório e rode ls .git. Você vai ver HEAD (um arquivo de uma linha, com o texto ref: refs/heads/main), objects/ (todo o conteúdo, comprimido e endereçado por hash), refs/heads/ (um arquivo por branch, contendo o hash do commit) e config (as configurações locais). Rode cat .git/HEAD e cat .git/refs/heads/main. O segundo arquivo tem exatamente 41 bytes: o hash do último commit e uma quebra de linha. Uma branch é isso — um arquivo com um hash dentro.

3. Configurando o Git¶

Antes do primeiro commit, diga ao Git quem você é. Essa informação vai junto de cada commit e não pode ser corrigida depois sem reescrever o histórico:

git config --global user.name "Ana Souza"
git config --global user.email "ana.souza@gmail.com"

Use o mesmo e-mail da sua conta do GitHub; é assim que o site liga os commits ao seu perfil e conta as contribuições.

Mais quatro ajustes que evitam problemas conhecidos (no Windows, a chave core.autocrlf recebe true em vez de input):

git config --global init.defaultBranch main       # nome da branch inicial
git config --global core.editor "code --wait"     # VS Code como editor de mensagens
git config --global pull.rebase false             # git pull faz merge (padrão explícito)
git config --global core.autocrlf input           # Linux e macOS
git config --list --show-origin                   # confere tudo

O que é o autocrlf? Windows termina linhas com dois caracteres (CR + LF); Linux e macOS, com um só (LF). Sem configuração, um arquivo salvo no Windows aparece como "todas as linhas mudaram" para quem está no Linux. Com autocrlf, o Git converte na entrada e na saída, e o aviso warning: LF will be replaced by CRLF que você viu no Capítulo 01 passa a ser inofensivo — ele está apenas anunciando a conversão.

O --show-origin mostra cada chave, o valor e de qual arquivo ela veio (~/.gitconfig para o global, .git/config para o do projeto). Configurações do projeto vencem as globais — útil quando um repositório precisa de outro e-mail.

💡 Dica Apelidos economizam digitação: git config --global alias.s "status -s" e git config --global alias.lg "log --oneline --graph --decorate --all" fazem git s e git lg funcionarem.

4. O primeiro repositório¶

4.1 git init e o primeiro commit¶

Entre na pasta do projeto e transforme-a em repositório:

cd ~/weblab/site-evento
git init
git status

O git init responde Initialized empty Git repository in /home/ana/weblab/site-evento/.git/. Nada mais mudou — os arquivos continuam iguais, apenas ganharam uma pasta .git ao lado. O git status mostra:

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    contato.html
    css/
    img/
    index.html
    inscricao.html
    js/
    palestrantes.html
    programacao.html

Tudo está não rastreado: o Git enxerga os arquivos, mas não cuida deles ainda. Prepare e commite:

git add .
git status -s
git commit -m "Estrutura inicial do site do evento com as cinco páginas"

O git status -s (short) é a versão compacta, de duas colunas: a primeira mostra o estado na área de preparação, a segunda no diretório de trabalho. Aqui ele imprime uma linha A <arquivo> por página. A = adicionado; as outras letras que você vai ver são M (modificado), D (apagado), R (renomeado) e ?? (não rastreado).

4.2 Mensagens de commit que servem para alguma coisa¶

A mensagem é lida por você mesmo daqui a três semanas, procurando quando o menu quebrou. Duas regras bastam:

• Imperativo, presente, em português: "Adiciona menu responsivo", não "adicionei" nem "adicionando".
• Diga o quê e, se não for óbvio, o porquê. O como já está no diff.

Para uma mensagem com corpo (título curto, linha em branco, explicação), rode git commit sem -m: o VS Code abre (por causa do core.editor), você escreve, salva e fecha a aba. O Git usa o texto.

Muitos times adotam Conventional Commits, um formato com prefixo: feat: para funcionalidade nova, fix: para correção, docs: para documentação, style: para formatação, refactor: para reorganização sem mudar comportamento e chore: para tarefas de infraestrutura — por exemplo, fix: corrige link quebrado para programacao.html. Não é obrigatório no WebLab, mas adote: o histórico fica legível e você já chega no mercado falando a língua.

4.3 Lendo o histórico¶

git log --oneline                              # uma linha por commit
git log --oneline --graph --decorate --all     # com o desenho das branches
git log --stat                                 # quantas linhas mudaram em cada arquivo
git log -3                                     # só os três últimos
git log --author="Ana"                         # filtra por autor
git log -- css/estilo.css                      # só os commits que tocaram nesse arquivo

Saída de git log --oneline --graph --decorate --all em um projeto com duas branches:

*   9c1d2e4 (HEAD -> main) Mescla menu-responsivo em main
|\
| * 4b7a0f1 (menu-responsivo) Fecha o menu ao clicar em um link
| * e21c8ad Adiciona botão hambúrguer e media query
|/
* a3f9c21 Estrutura inicial do site do evento com as cinco páginas

Para ver o conteúdo de um commit específico, git show a3f9c21 (mensagem e diff completo), git show a3f9c21 --stat (só a lista de arquivos) ou git show a3f9c21:index.html (o arquivo como estava naquele commit).

4.4 git diff: o que exatamente mudou¶

git diff              # diretório de trabalho × área de preparação
git diff --staged     # área de preparação × último commit
git diff HEAD         # diretório de trabalho × último commit (os dois juntos)
git diff main menu-responsivo   # diferença entre duas branches

Um diff se lê assim:

--- a/css/estilo.css
+++ b/css/estilo.css
@@ -12,7 +12,7 @@ header {
   display: flex;
-  background: #1b6b4a;
+  background: var(--cor-primaria);
   padding: 1rem;

- é a linha removida, + a adicionada, e as linhas sem sinal são contexto. O @@ -12,7 +12,7 @@ diz que o trecho começa na linha 12 e tem 7 linhas nos dois lados.

🔬 Investigue Dentro do site-evento, abra o index.html e troque o texto do <h1>. Não salve ainda. Rode git status: nada mudou para o Git (ele lê o arquivo em disco). Agora salve e rode git status de novo — o arquivo aparece como modified. Rode git diff e leia as linhas -/+. Agora git add index.html, e rode git diff outra vez: sai vazio, porque a mudança saiu do diretório de trabalho e foi para a área de preparação. Rode git diff --staged e ela reaparece. Essas duas telas explicam as três áreas melhor do que qualquer diagrama.

5. .gitignore, README.md e .gitattributes¶

5.1 O que nunca entra no repositório¶

Três categorias de arquivo ficam de fora. O regenerável (node_modules/, dist/, build/, .vite/), que qualquer pessoa recria com npm install e npm run build. O secreto (.env, chaves de API, credenciais de banco): um segredo commitado está público para sempre, mesmo que você apague depois, porque continua no histórico. E o que é do seu computador: .DS_Store (macOS), Thumbs.db (Windows), *.log e pastas de configuração pessoal do editor.

O arquivo .gitignore, na raiz, lista o que o Git deve ignorar:

.gitignore

# Dependências e artefatos de build
node_modules/
dist/
build/
.vite/

# Variáveis de ambiente e segredos
.env
.env.*.local
*.pem
*.key

# Logs e arquivos do sistema operacional
*.log
.DS_Store
Thumbs.db

# Editores (mantemos as configurações compartilhadas do projeto)
.idea/
.vscode/*
!.vscode/settings.json

A sintaxe é simples: uma linha por padrão e # para comentário; barra no fim (dist/) significa "só pastas com esse nome"; * casa qualquer coisa dentro de um nível e **/ casa qualquer profundidade; barra no começo (/temp) ancora na raiz do repositório; e ! reverte a regra anterior — é o que faz .vscode/settings.json ser versionado mesmo com .vscode/* ignorado.

⚠️ Atenção O .gitignore só vale para arquivos não rastreados. Se você já commitou node_modules/, acrescentar a linha não resolve: o Git continua cuidando dele. Remova do rastreamento sem apagar do disco com git rm -r --cached node_modules e commite. E se o que vazou foi um .env com senha, trocar a senha é obrigatório — apagar o arquivo não apaga o histórico.

5.2 README.md: a capa do projeto¶

O GitHub renderiza o README.md na página inicial do repositório. É a primeira coisa que quem avalia o projeto, um colega ou um recrutador vai ler. Cinco seções bastam: o que é, como rodar, estrutura, estado atual e autoria.

README.md

# Site do Evento — Semana Acadêmica de Sistemas de Informação

Site institucional de cinco páginas para a Semana Acadêmica, construído na
trilha Nível 1 do WebLab. HTML5 semântico, CSS3 responsivo e
JavaScript sem framework.

Como rodar: clone, abra a pasta no VS Code e clique em **Go Live** (extensão
Live Server) com o `index.html` aberto. O site sobe em `http://127.0.0.1:5500`.

    git clone https://github.com/ana-souza/site-evento.git
    cd site-evento && code .

Estrutura: `index.html`, `programacao.html`, `palestrantes.html`,
`inscricao.html` e `contato.html` na raiz; estilos em `css/estilo.css`,
scripts em `js/script.js`, imagens em `img/`.

Estado atual: as cinco páginas em HTML semântico e o menu de navegação estão
prontos; faltam o layout responsivo e a validação do formulário de inscrição.

Ana Souza — Introdução ao Desenvolvimento Web,
seu nome. Código sob licença MIT.

Repare que o bloco de comandos dentro do README está indentado com quatro espaços em vez de cercado por crases — é a outra forma de marcar código em Markdown, e ela evita confusão quando o arquivo é mostrado dentro de outro documento. No seu projeto, use títulos ## para separar as cinco seções e uma lista de tarefas (- [x] e - [ ]) no estado atual: o GitHub a renderiza com caixas de seleção.

5.3 .gitattributes: o fim da guerra CRLF¶

O core.autocrlf da §3 é uma configuração da sua máquina. O .gitattributes é do projeto, e vale para todo mundo que clonar:

.gitattributes

# Normaliza o fim de linha de todo arquivo de texto para LF no repositório
* text=auto eol=lf

# Arquivos binários: nunca converter
*.png binary
*.jpg binary
*.webp binary
*.pdf binary
*.woff2 binary

Com isso, o repositório guarda tudo com LF, independentemente de quem commitou, e cada máquina recebe o que precisa ao clonar. É uma linha que evita diffs de mil linhas quando a dupla usa sistemas diferentes.

6. Desfazendo com segurança¶

Quatro situações, quatro comandos. Escolher errado aqui é a principal causa de trabalho perdido no semestre.

"Editei e quero voltar ao último commit." O git restore descarta o que está só no diretório de trabalho — e apaga de vez o que você escreveu e não commitou:

git restore index.html            # descarta as mudanças de um arquivo (. = todos)
git restore --staged index.html   # tira da área de preparação, mantendo as edições

"O último commit está errado." Se você errou a mensagem ou esqueceu um arquivo e ainda não deu push, git add arquivo-esquecido.html seguido de git commit --amend -m "nova mensagem" substitui o último commit por um novo, com outro hash. Nunca use em commit que já foi para o GitHub e que outra pessoa possa ter baixado.

"Quero desfazer o commit, mas manter o trabalho."

git reset --soft HEAD~1     # desfaz o commit; tudo volta para a área de preparação
git reset HEAD~1            # desfaz o commit; tudo volta para o diretório de trabalho
git reset --hard HEAD~1     # desfaz o commit E apaga as mudanças — o perigoso

"Preciso desfazer um commit que já está no GitHub." Use git revert a3f9c21. O revert não apaga nada: cria um commit novo que desfaz o que aquele commit fez. É o único método seguro quando o histórico já é público, porque não reescreve nada que alguém já baixou — e --amend e reset reescrevem.

⚠️ Atenção git reset --hard e git restore sem nada preparado são as duas únicas formas comuns de perder trabalho de verdade com Git. Antes de qualquer um dos dois, rode git status e leia a lista do que vai sumir. Se estiver em dúvida, git stash (§10.1) guarda tudo sem apagar.

7. Branches, merge e conflitos¶

7.1 Criar e trocar¶

git switch -c menu-responsivo    # cria a branch e já muda para ela
git switch main                  # volta para main
git branch -a                    # lista as branches locais (* na atual) e as remotas
git branch -d menu-responsivo    # apaga (só se já foi mesclada; -D força)

O comando antigo para isso era git checkout -b; ele continua funcionando, mas git switch existe justamente porque checkout fazia coisas demais e confundia. Use switch para branches e restore para arquivos.

Regra de ouro do WebLab: main sempre funciona. Toda mudança nasce em uma branch com nome descritivo (menu-responsivo, validacao-inscricao, corrige-contraste) e só volta para main quando está pronta.

7.2 Mesclar¶

Estando em main:

git switch main
git merge menu-responsivo
git merge --no-ff menu-responsivo   # força sempre um commit de mesclagem

Dois desfechos possíveis. No fast-forward, se main não recebeu nenhum commit desde que a branch nasceu, o Git apenas move o ponteiro de main para frente, sem criar commit novo. No commit de mesclagem, quando as duas branches evoluíram, o Git cria um commit com dois pais — é o 9c1d2e4 do grafo da §4.3. O --no-ff força o segundo caso mesmo quando o primeiro seria possível, e o histórico fica mais legível: cada funcionalidade vira um "nó" visível no grafo.

7.3 Conflitos¶

Um conflito acontece quando as duas branches mudaram as mesmas linhas do mesmo arquivo. O Git não adivinha qual está certa e para:

Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.

Abra o arquivo. O Git escreveu marcadores nele:

<h1>
<<<<<<< HEAD
  Semana Acadêmica de Sistemas de Informação
=======
  Semana Acadêmica de Sistemas de Informação — 12ª edição
>>>>>>> menu-responsivo
</h1>

Leia assim: entre <<<<<<< HEAD e ======= está a versão da branch em que você está; entre ======= e >>>>>>> está a versão da branch que você está trazendo.

Resolver é editar o trecho à mão até ficar como deve ficar — pode ser uma das duas, ou uma terceira redação — e apagar as três linhas de marcador. Depois:

git diff --name-only --diff-filter=U   # lista só os arquivos ainda em conflito
git add index.html
git commit              # sem -m: o Git já sugere a mensagem de mesclagem
git merge --abort       # alternativa: desiste e volta ao estado anterior

Quando um arquivo inteiro deve vir de um lado só, git checkout --ours index.html aceita a versão da branch atual e --theirs a que está chegando. O VS Code também mostra os conflitos com botões (Accept Current Change, Accept Incoming Change, Accept Both Changes); use-os, mas leia o resultado: aceitar "both" com frequência gera HTML duplicado.

🧠 Você sabia? Conflito não é erro, e não é sinal de que alguém fez algo errado. É o Git avisando que uma decisão humana é necessária. Times grandes tratam a frequência de conflitos como métrica de organização: muitos conflitos indicam branches que vivem tempo demais separadas. A receita é a mesma em qualquer time: branches curtas, mescladas em dias e não em semanas, e git pull no começo de cada sessão de trabalho.

8. GitHub e o gh¶

8.1 Git não é GitHub¶

Git é o programa que roda na sua máquina e guarda o histórico. GitHub é um site que hospeda repositórios Git e acrescenta o que o Git não tem: interface web, controle de acesso, issues, pull requests, ações automatizadas e páginas publicadas. Existem concorrentes (GitLab, Bitbucket, Codeberg) com as mesmas ideias. Você pode usar Git sem GitHub a vida toda, mas não pode publicar um site, colaborar ou entregar um link sem um servidor remoto.

Crie sua conta em https://github.com usando o mesmo e-mail do git config user.email. Escolha um nome de usuário que você mostraria a um empregador: ele vai virar parte da URL de todos os seus projetos e, no Capítulo 03, do endereço do seu site (ana-souza.github.io).

Enquanto estiver lá, ative a autenticação em duas etapas — o GitHub a exige de quem contribui com código.

8.2 O GitHub CLI¶

O gh é o cliente oficial de linha de comando. Ele resolve a autenticação e permite criar repositórios, abrir pull requests e revisar código sem sair do terminal.

Instalação:

sudo apt install gh                  # Ubuntu/Debian
brew install gh                      # macOS, com Homebrew
winget install --id GitHub.cli       # Windows, em um PowerShell

Se o apt da sua distribuição trouxer uma versão antiga, use o repositório oficial descrito em https://github.com/cli/cli/blob/trunk/docs/install_linux.md.

Conferir e autenticar com gh --version e gh auth login. O login faz quatro perguntas no terminal:

1. What account do you want to log into? → GitHub.com
2. What is your preferred protocol for Git operations? → HTTPS (mais simples; a §8.3 mostra a alternativa)
3. Authenticate Git with your GitHub credentials? → Yes (o gh passa a responder pelo git push, sem pedir senha)
4. How would you like to authenticate? → Login with a web browser — o terminal mostra um código de oito caracteres, você o cola na página que abrir e autoriza.

Confira com gh auth status. Saída esperada: ✓ Logged in to github.com account ana-souza (keyring) e a lista de escopos.

💡 Dica Em uma máquina de laboratório, nunca deixe sua sessão do gh aberta. Faça gh auth logout ao terminar, ou use gh auth login com o navegador em janela anônima. O token guardado dá acesso de escrita a todos os seus repositórios.

8.3 SSH, se você preferir¶

Com HTTPS + gh, o push já funciona sem senha. Se quiser chaves SSH (útil quando você também acessa um servidor, como no Capítulo 06), gere a chave aceitando o caminho padrão ~/.ssh/id_ed25519, envie a pública e teste:

ssh-keygen -t ed25519 -C "ana.souza@gmail.com"
gh ssh-key add ~/.ssh/id_ed25519.pub --title "Notebook da Ana"
ssh -T git@github.com

Resposta esperada: Hi ana-souza! You've successfully authenticated, but GitHub does not provide shell access. Isso não é erro — o GitHub só aceita Git, não sessão de terminal.

8.4 Criar o repositório remoto e publicar¶

Dentro da pasta que já é um repositório local:

gh repo create site-evento --public --source=. --remote=origin --push

O --public deixa o repositório visível para qualquer pessoa (--private faz o contrário), --source=. usa o repositório Git da pasta atual em vez de criar um vazio, --remote=origin cadastra a URL remota com o apelido origin e --push já envia a branch atual.

Sem o gh, você cria o repositório vazio pela interface web e liga os dois no terminal:

git remote add origin https://github.com/ana-souza/site-evento.git
git remote -v
git push -u origin main

O -u (de upstream) liga a branch local main à remota origin/main. Depois disso, git push e git pull sem argumentos já sabem para onde ir. Para abrir o repositório no navegador, gh repo view --web; em outra máquina, gh repo clone ana-souza/site-evento (ou git clone <url>) traz o histórico inteiro, e não só os arquivos — por isso git log funciona imediatamente na máquina nova, sem internet.

9. Pull request: a conversa sobre o código¶

9.1 O que é¶

Um pull request (PR) é um pedido: "revisem estas mudanças e, se estiverem boas, coloquem na main". Ele mostra o diff, permite comentários linha a linha, roda verificações automáticas (Capítulo 09) e registra a decisão.

Em um projeto de uma pessoa, o PR parece burocracia — mas é justamente aí que ele ensina: você se obriga a reler o próprio diff antes de mesclar, e o número de bugs bobos cai. Em dupla, ele é o único jeito civilizado de trabalhar. O ciclo completo:

main ──●──────────────────────────────●── (merge do PR)
        \ ●───────●───────●──────────/     branch da tarefa
       commit  commit  push      revisão

9.2 Abrindo o PR¶

git switch -c menu-responsivo
git add css/estilo.css js/script.js index.html
git commit -m "Adiciona menu hamburguer responsivo abaixo de 768px"
git push -u origin menu-responsivo
gh pr create --base main --head menu-responsivo \
  --title "Menu responsivo com botão hambúrguer" \
  --body "Abaixo de 768px o menu vira um botão. Fecha ao clicar em um link e ao apertar Esc. Testado no modo dispositivo do DevTools em 375px e 768px."

Três opções que valem conhecer: --fill usa a mensagem do commit como título e corpo, --draft abre como rascunho (ninguém revisa ainda) e --web abre o formulário no navegador. O gh imprime a URL do PR — guarde-a: é o link que você compartilha quando a entrega envolve revisão.

9.3 Revisando¶

gh pr list                          # PRs abertos no repositório
gh pr view 1                        # descrição, autor, estado
gh pr diff 1                        # o diff completo, no terminal
gh pr checkout 1                    # baixa a branch do PR para testar na sua máquina
gh pr checks 1                      # resultado das verificações automáticas
gh pr review 1 --comment --body "O botão precisa de aria-expanded."
gh pr review 1 --approve
gh pr review 1 --request-changes --body "O menu não fecha com Esc."

Uma revisão útil olha quatro coisas, nesta ordem: funciona? (baixe a branch e teste), está claro? (nomes, indentação), quebra algo? (links, outras páginas), falta alguma coisa? (acessibilidade, tratamento de erro, alt nas imagens).

⚠️ Atenção O GitHub não deixa você aprovar o seu próprio pull request. Se tentar, o gh responde Can not approve your own pull request. Isso não impede o merge em um repositório pessoal — apenas o carimbo de aprovação. Nos trabalhos em dupla, cada um aprova o PR do outro.

9.4 Mesclando¶

gh pr merge 1 --squash --delete-branch

Três estratégias, e quando usar cada uma:

Depois do merge, atualize sua máquina com git switch main e git pull. O --delete-branch do gh apaga as duas cópias da branch — a do GitHub e a da sua máquina —, então não sobra nada para um git branch -d apagar depois. Se você mesclar pelo site, sem o --delete-branch, aí sim: git push origin --delete menu-responsivo remove a remota e git branch -d menu-responsivo remove a local.

9.5 Proteção de branch¶

No repositório do GitHub, em Settings → Branches → Add branch ruleset, você exige que a main só receba código por PR e só depois de uma aprovação — é o que impede o git push direto no dia do prazo. No Capítulo 09, essa mesma tela passa a exigir que os testes automáticos passem antes do merge.

10. Stash, tags e o que mais você vai usar¶

10.1 git stash: guardar sem commitar¶

Você está no meio de uma alteração e precisa trocar de branch agora (o colega achou um bug em produção). Commitar pela metade polui o histórico; perder o trabalho, nem pensar:

git stash push -u -m "menu pela metade"   # -u inclui arquivos não rastreados
git switch main
git switch menu-responsivo      # depois de resolver o urgente e commitar
git stash list                  # stash@{0}: On menu-responsivo: menu pela metade
git stash pop                   # devolve as mudanças e remove da pilha

Na pilha também valem git stash apply stash@{0} (devolve mantendo o item), git stash show -p stash@{0} (mostra o diff guardado), git stash drop (descarta um) e git stash clear (esvazia tudo).

10.2 Tags: marcar versões¶

Uma tag é um nome fixo para um commit. Serve para marcar entregas:

git tag -a v1.0.0 -m "Marco 1: cinco páginas em HTML"
git push origin v1.0.0   # tags não sobem no push comum; --tags envia todas

O git tag -l lista as existentes. O -a cria uma tag anotada, que guarda autor, data e mensagem — é a que se usa em entregas. Sem -a, a tag é apenas um apelido do hash. No GitHub, uma tag pode virar uma release, com notas e arquivos anexados:

gh release create v1.0.0 --title "Marco 1 — site do evento" \
  --notes "Cinco páginas em HTML semântico, menu de navegação e formulário de inscrição."

10.3 Comandos de resgate¶

git reflog                      # todo movimento do HEAD, inclusive o que "sumiu"
git blame css/estilo.css        # quem escreveu cada linha e em qual commit
git bisect start                # busca binária pelo commit que introduziu um bug
git clean -n                    # lista arquivos não rastreados que seriam apagados (-fd apaga)

O git reflog é a rede de segurança: mesmo depois de um git reset --hard infeliz, o commit antigo continua listado lá por semanas, e git switch -c recuperado <hash> traz tudo de volta.

11. Trabalhando em dupla¶

O trabalho em dupla (nesta trilha ou em qualquer projeto real) segue sempre o mesmo ciclo:

1. Antes de começar a trabalhar, atualize: git switch main && git pull.
2. Crie uma branch por tarefa (git switch -c inscricao-validacao) e faça commits pequenos e frequentes, um assunto por commit.
3. Publique cedo: git push -u origin inscricao-validacao já no primeiro commit, mesmo inacabado (gh pr create --draft). O colega vê que você está mexendo ali.
4. Abra o PR, peça revisão e responda aos comentários com novos commits — o PR se atualiza sozinho a cada push.
5. Merge com squash, apague a branch, volte para a main e dê git pull.

Duas situações inevitáveis:

A main andou enquanto você trabalhava. Traga as novidades para a sua branch antes de pedir o merge, resolvendo os conflitos ali e não na main:

git switch main && git pull
git switch inscricao-validacao
git merge main

O push foi recusado.

! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/ana-souza/site-evento.git'
hint: Updates were rejected because the remote contains work that you do not have locally.

Significa que o remoto tem commits que você não tem. A resposta certa é git pull (que mescla) e depois git push. A resposta errada é git push --force, que apaga o trabalho do colega no servidor.

Combine com a dupla, no primeiro dia: quem mexe em qual arquivo (um no HTML das páginas, outro no CSS, por exemplo), que a main é intocável e só recebe merge de PR, e que ninguém dá --force em branch compartilhada.

🔬 Investigue Simule uma dupla sozinho, em duas pastas. Clone o mesmo repositório duas vezes: git clone <url> copia-a e git clone <url> copia-b. Em copia-a, mude o <h1> do index.html, commite e dê push. Em copia-b, sem dar pull, mude a mesma linha, commite e tente o push. Leia a mensagem de rejeição inteira. Agora rode git pull em copia-b: o conflito aparece. Resolva, commite e dê push. Volte em copia-a e rode git pull para ver o resultado final. Você acabou de viver, em dez minutos, o ciclo que trava a maioria dos trabalhos em grupo.

🚀 Passo a passo — O site do evento versionado, no GitHub e com um PR mesclado¶

Ao fim destes passos, site-evento é um repositório Git com histórico legível, existe em https://github.com/<seu-usuario>/site-evento, tem README.md, .gitignore e .gitattributes, e uma funcionalidade nova entrou na main por um pull request revisado e mesclado. Faça na ordem.

Passo 1 — Configurar o Git e iniciar o repositório¶

Rode os seis git config --global da §3 (no Windows, core.autocrlf true) e confira com git config --list --show-origin. Depois:

cd ~/weblab/site-evento
git init
git add .
git status -s
git commit -m "Estrutura inicial do site do evento com as cinco páginas"
git log --oneline

Esperado: uma linha, com o hash curto e a mensagem.

Passo 2 — .gitignore, .gitattributes e README.md¶

Crie os três arquivos na raiz com o conteúdo das §5.1, §5.3 e §5.2 (adaptando o README ao seu projeto e ao seu nome). Depois commite e teste se o .gitignore está valendo:

git add .gitignore .gitattributes README.md
git commit -m "Adiciona README, .gitignore e .gitattributes"
mkdir -p node_modules && touch node_modules/teste.js .env
git status -s
rm -rf node_modules .env

Esperado: o git status -s não menciona node_modules nem .env.

Passo 3 — Autenticar o gh e publicar¶

Instale o GitHub CLI conforme a §8.2 e autentique-se, respondendo GitHub.com, HTTPS, Yes e Login with a web browser:

gh --version
gh auth login
gh auth status
gh repo create site-evento --public --source=. --remote=origin --push
git remote -v
gh repo view --web

Esperado: o navegador abre o repositório com os arquivos e o README renderizado.

Passo 4 — Branch com a funcionalidade nova¶

Crie a branch com git switch -c menu-responsivo e acrescente o botão ao menu de index.html, dentro do <header>, antes da lista de links:

index.html

<header class="cabecalho">
  <a class="logo" href="index.html">Semana Acadêmica</a>
  <button class="botao-menu" id="botaoMenu" aria-expanded="false"
          aria-controls="menuPrincipal" aria-label="Abrir menu de navegação">☰</button>
  <nav>
    <ul class="menu" id="menuPrincipal">
      <li><a href="index.html">Início</a></li>
      <li><a href="programacao.html">Programação</a></li>
      <li><a href="palestrantes.html">Palestrantes</a></li>
      <li><a href="inscricao.html">Inscrição</a></li>
      <li><a href="contato.html">Contato</a></li>
    </ul>
  </nav>
</header>

css/estilo.css (acrescente ao fim do arquivo)

/* Menu responsivo: o botão só aparece em telas estreitas */
.botao-menu {
  display: none;
  font-size: 1.5rem;
  background: none;
  border: 0;
  color: inherit;
  cursor: pointer;
  padding: 0.25rem 0.5rem;
}

@media (max-width: 768px) {
  .botao-menu { display: block; }
  .menu {
    display: none;
    flex-direction: column;
    width: 100%;
    gap: 0.5rem;
    padding: 1rem 0;
  }
  .menu.aberto { display: flex; }
}

js/script.js (acrescente ao fim do arquivo)

// Menu responsivo: abre e fecha a lista de links em telas estreitas
const botaoMenu = document.querySelector('#botaoMenu')
const menuPrincipal = document.querySelector('#menuPrincipal')

function definirEstado(aberto) {
  menuPrincipal.classList.toggle('aberto', aberto)
  botaoMenu.setAttribute('aria-expanded', String(aberto))
  botaoMenu.setAttribute('aria-label', aberto ? 'Fechar menu de navegação' : 'Abrir menu de navegação')
}

botaoMenu.addEventListener('click', () => definirEstado(!menuPrincipal.classList.contains('aberto')))
menuPrincipal.addEventListener('click', (evento) => {
  if (evento.target.tagName === 'A') definirEstado(false)
})
document.addEventListener('keydown', (evento) => {
  if (evento.key === 'Escape') definirEstado(false)
})

Teste no navegador (Live Server + modo dispositivo em 375 px) e commite:

git add index.html css/estilo.css js/script.js
git commit -m "Adiciona menu hamburguer responsivo abaixo de 768px"
git push -u origin menu-responsivo

Passo 5 — Abrir e revisar o pull request¶

gh pr create --base main --head menu-responsivo \
  --title "Menu responsivo com botão hambúrguer" \
  --body "Abaixo de 768px o menu vira um botão com aria-expanded. Fecha ao clicar em um link e com Esc. Testado no modo dispositivo em 375px e 768px."
gh pr list
gh pr diff
gh pr review --comment --body "Diff conferido: aria-expanded muda junto com a classe, e o Esc fecha. Aprovado para merge."

Se você estiver em dupla, quem não abriu o PR roda gh pr checkout <numero>, testa no navegador e depois gh pr review <numero> --approve.

Passo 6 — Mesclar, limpar e marcar a entrega¶

gh pr merge --squash --delete-branch
git switch main
git pull
git log --oneline --graph --decorate --all
git tag -a v1.0.0 -m "Site do evento com as cinco páginas e menu responsivo"
git push origin v1.0.0
gh release create v1.0.0 --title "v1.0.0 — site do evento" \
  --notes "Cinco páginas em HTML semântico, CSS com menu responsivo e navegação por teclado."
gh repo view --web

Esperado: o histórico da main mostra três commits, o último com a mensagem do PR, e a release aparece na lateral da página do repositório.

Como conferir¶

🧪 Laboratório¶

Nível A — Fixação¶

A1. Um arquivo aparece em git status sob Changes not staged for commit. Em qual das três áreas ele está? E se aparecer sob Changes to be committed? E sob Untracked files?

A2. Preveja a saída. Você editou index.html e css/estilo.css, rodou git add index.html e em seguida git diff e git diff --staged. Qual arquivo aparece em cada um dos dois comandos, e por quê?

A3. Para cada situação, diga qual comando usar: (a) descartar uma edição não commitada; (b) tirar um arquivo da área de preparação; (c) corrigir a mensagem do último commit local; (d) desfazer um commit que já está no GitHub; (e) guardar o trabalho pela metade para trocar de branch.

A4. Você acrescentou node_modules/ ao .gitignore, mas a pasta continua aparecendo em git status. Explique por quê e escreva a sequência de comandos que resolve sem apagar a pasta do disco.

A5. Um index.html em conflito tem <<<<<<< HEAD, <h1>Semana Acadêmica</h1>, =======, <h1>Semana Acadêmica de Sistemas de Informação</h1> e >>>>>>> titulo-longo, nesta ordem. Diga qual versão pertence a qual branch, e o que precisa ser feito no arquivo antes do git add.

A6. Qual a diferença entre git fetch e git pull? E entre gh pr merge --squash e gh pr merge --merge, do ponto de vista do que aparece em git log --oneline da main?

Nível B — Aplicação¶

B1. Histórico limpo em três commits. Comece de uma pasta nova (git init), com um index.html de esqueleto. Faça exatamente três commits, nesta ordem: um só com o esqueleto HTML, um só com o CSS ligado por <link>, e um só com o <script> e o script.js. As três mensagens devem estar no imperativo e ter menos de 60 caracteres.

Resultado esperado: git log --oneline mostra três linhas; git show --stat de cada commit lista apenas os arquivos daquele assunto (nenhum commit toca em arquivo de outro assunto).

B2. Conflito provocado e resolvido. No site-evento, crie duas branches a partir da main: titulo-curto e titulo-longo. Em cada uma, altere a mesma linha do <h1> do index.html e commite. Volte para a main, mescle a primeira (vai passar), e mescle a segunda (vai dar conflito). Resolva escolhendo uma terceira redação, diferente das duas.

Resultado esperado: git log --oneline --graph --all mostra o desenho com as duas branches e o commit de mesclagem; o index.html final tem a terceira redação e nenhum marcador <<<<<<<.

B3. Arqueologia do repositório. Escolha um repositório público conhecido (por exemplo https://github.com/vuejs/core), clone-o e responda, só pelo terminal: quantos commits ele tem; quem são os cinco maiores autores por número de commits; qual foi o primeiro commit (hash, data e mensagem); qual arquivo tem mais commits no histórico.

Resultado esperado: um arqueologia.md com as quatro respostas e o comando exato usado em cada uma.

B4. Fluxo completo em dupla. Com um colega (ou com duas cópias clonadas, como na §11): a pessoa A adiciona o repositório à conta dela e convida a B em Settings → Collaborators. Cada uma cria uma branch, faz uma alteração em página diferente, abre um PR e revisa e aprova o PR da outra. Ao final, as duas alterações estão na main.

Resultado esperado: dois PRs mesclados, cada um com uma revisão de aprovação de outra pessoa; git log --oneline na main mostra as duas funcionalidades.

Nível C — Desafio¶

C1. Resgate depois do desastre. Prepare o cenário: em um repositório de teste com cinco commits, rode git reset --hard HEAD~3. Os três últimos commits sumiram do git log. Recupere-os sem clonar de novo e sem usar o GitHub, deixando a main exatamente como estava antes. Depois, repita o desastre de outra forma: crie uma branch experimento, commite algo nela, volte para a main e apague a branch com git branch -D experimento. Recupere o commit perdido.

🏆 Desafios¶

🐛 Erros comuns¶

🏠 Para praticar depois da aula (1 h)¶

Leve o seu projeto autoral (o site com o tema que você escolheu na sua trilha) para o GitHub, com histórico decente:

1. Rode git init na pasta do projeto autoral e crie .gitignore, .gitattributes e README.md (com as seções: o que é, como rodar, estrutura, estado atual em checklist e autoria).
2. Faça no mínimo quatro commits separados por assunto, com mensagens no imperativo e menos de 60 caracteres cada.
3. Publique com gh repo create <nome> --public --source=. --remote=origin --push.
4. Crie a branch melhoria-<algo>, faça uma melhoria real (acessibilidade, responsividade, um texto que estava faltando), commite, dê push e abra um pull request com descrição de três linhas explicando o que mudou e por quê.
5. Mescle o PR com --squash --delete-branch, volte para a main, dê git pull e crie a tag anotada v0.1.0.

Critério de pronto: git log --oneline na main mostra cinco ou mais commits com mensagens legíveis; o repositório é público; o README aparece renderizado na página; existe um PR com estado MERGED; a tag v0.1.0 está no GitHub; git status diz working tree clean.

Guarde no seu repositório: o link do repositório público e o link do pull request mesclado. Nada de .zip daqui em diante.

✅ Está no ar quando…¶

• [ ] git log --oneline --graph --decorate --all no site-evento mostra um histórico com pelo menos três commits e o traço da branch mesclada.
• [ ] git status responde nothing to commit, working tree clean.
• [ ] https://github.com/<seu-usuario>/site-evento abre, é público e mostra o README.md renderizado.
• [ ] Criar um arquivo .env na pasta não faz nada aparecer em git status.
• [ ] gh pr list --state merged lista o pull request do menu responsivo.
• [ ] git branch -a mostra só main e remotes/origin/main — as branches de tarefa foram apagadas depois do merge.
• [ ] A tag v1.0.0 existe local (git tag -l) e no GitHub (na lateral da página do repositório).
• [ ] Você explica, sem consultar, a diferença entre git restore, git reset e git revert, e sabe o que fazer quando aparece CONFLICT (content): Merge conflict in ….

📚 Para aprofundar¶

• Pro Git, de Scott Chacon e Ben Straub — https://git-scm.com/book/pt-br/v2 — livro oficial, gratuito e em português. Leia os capítulos 2 (Fundamentos) e 3 (Ramificação), que cobrem tudo deste capítulo com mais profundidade.
• Documentação de referência do Git — https://git-scm.com/docs — a página de cada comando; comece por git-status, git-switch e git-restore. GitHub Docs em português — https://docs.github.com/pt — contas, repositórios, colaboração e a seção "Sobre pull requests".
• GitHub Skills — https://skills.github.com — cursos interativos curtos, feitos dentro de repositórios reais; o "Introduction to GitHub" leva menos de uma hora.
• Manual do GitHub CLI — https://cli.github.com/manual/ — todos os comandos do gh, com exemplos por subcomando.
• Learn Git Branching — https://learngitbranching.js.org/?locale=pt_BR — visualizador interativo de branches, merge e rebase; o melhor lugar para "ver" o grafo se formando.
• Conventional Commits — https://www.conventionalcommits.org/pt-br/ — a especificação do formato de mensagens usado na §4.2.
• Documentação do .gitignore — https://git-scm.com/docs/gitignore — e a coleção de modelos por linguagem em https://github.com/github/gitignore.
• MILETTO, Evandro M.; BERTAGNOLLI, Silvia C. Desenvolvimento de software II. Bookman — capítulo sobre gerência de configuração e controle de versão.

No próximo capítulo, esse repositório deixa de ser só um backup: o GitHub Pages e a Netlify passam a servir o site-evento e o Café Cerrado em endereços públicos, e você descobre por que um href="/css/estilo.css" que funciona na sua máquina quebra no ar.

🎯 Objetivos de aprendizagem¶

Ao final deste capítulo você será capaz de:

• Explicar o que uma hospedagem estática faz (e o que ela não faz), por que ela é rápida e por que é gratuita para projetos como os seus.
• Publicar um repositório no GitHub Pages pelas configurações do site e pelo terminal (gh api), e ler o estado da publicação sem sair do terminal.
• Distinguir caminho relativo ao documento, relativo à raiz e absoluto, prever para onde cada um resolve e consertar um site que perde o CSS ao ser publicado em um subcaminho como usuario.github.io/site-evento/.
• Colocar favicon, ícone de tela inicial e site.webmanifest em um site publicado em subcaminho, sem depender do pedido automático que o navegador faz à raiz do domínio.
• Criar uma página 404.html que funciona em qualquer profundidade de URL, no GitHub Pages e na Netlify.
• Publicar na Netlify por arrastar-e-soltar e a partir do Git, com um netlify.toml que define diretório publicado, redirecionamentos e cabeçalhos.
• Comparar GitHub Pages, Netlify, Vercel e Cloudflare Pages e justificar a escolha para um projeto específico.
• Ler cache-control, etag e age com curl -I, explicar por que a versão antiga insiste em aparecer e resolver com recarga forçada e nomes versionados.
• Rodar o Lighthouse contra a URL pública e transformar o relatório em uma lista de correções concretas.

📋 Pré-requisitos¶

• [ ] Repositório site-evento no GitHub, público, com README.md e histórico limpo (Capítulo 02) — ou o repositório do seu projeto autoral.
• [ ] git e gh funcionando: gh auth status responde Logged in to github.com.
• [ ] curl instalado (curl --version) e o navegador com DevTools (Capítulo 01).
• [ ] Uma conta na Netlify (pode entrar com a conta do GitHub) — https://app.netlify.com.
• [ ] Node.js 22 LTS instalado, para rodar o Lighthouse com npx no fim do capítulo.

No Capítulo 02 o site-evento virou um repositório com histórico legível, um pull request mesclado e uma tag v1.0.0 — mas ele ainda só existe na sua máquina e em um repositório que só desenvolvedores sabem ler. Hoje ele ganha um endereço que você pode mandar para qualquer pessoa. E, no caminho, você resolve os dois problemas que o Capítulo 01 prometeu resolver aqui: o favicon.ico com 404 no console e a diferença entre caminho absoluto e relativo, que é a causa número um de "publiquei e o site ficou sem CSS".

🗺️ Roteiro¶

1. O que é uma hospedagem estática¶

1.1 Arquivos, não programas¶

Um site estático é uma pasta de arquivos: HTML, CSS, JavaScript, imagens, fontes. Quando alguém pede https://ana-souza.github.io/site-evento/programacao.html, o servidor procura o arquivo programacao.html dentro da pasta publicada e devolve os bytes. Ele não executa nada seu, não consulta banco, não decide nada. O JavaScript existe, mas roda no navegador de quem visita, não no servidor.

Isso é uma limitação enorme e, ao mesmo tempo, a razão de tudo o que vem a seguir ser fácil:

E o que ele não faz: guardar uma inscrição enviada por formulário, verificar uma senha, listar produtos de um banco, esconder uma chave de API. Tudo isso exige um processo rodando do lado do servidor — é o assunto do Capítulo 05. Por enquanto, se o seu formulário de inscrição precisa de fato receber respostas, a saída honesta é apontar o action para um serviço de formulários (a Netlify tem um embutido) ou usar mailto:.

1.2 CDN: por que o site fica perto de quem acessa¶

As quatro plataformas deste capítulo não guardam o seu site em um servidor só. Elas copiam os arquivos para uma CDN (Content Delivery Network): uma rede de servidores espalhados pelo mundo, com pontos de presença em várias cidades. Quem acessa de Sinop é atendido por um servidor perto de Sinop; quem acessa de Lisboa, por um perto de Lisboa.

   você faz                     a plataforma copia para
   git push  ──►  build  ──►  dezenas de servidores (CDN)
                                │        │        │
                             São Paulo  Miami   Frankfurt
                                │        │        │
                             visitante visitante visitante

O ganho é de latência, não de banda: cada ida e volta até um servidor a 8.000 km custa uns 200 ms, e uma página faz várias idas e voltas. É por isso que um site estático bem publicado costuma abrir em menos de um segundo, mesmo em 4G.

🧠 Você sabia? O GitHub Pages nasceu em 2008 e, até hoje, roda por padrão um gerador de sites chamado Jekyll, escrito por Tom Preston-Werner — um dos fundadores do próprio GitHub — para publicar o blog dele. É por isso que o GitHub Pages tem manias estranhas de gerador de blog: pastas cujo nome começa com _ recebem tratamento especial e podem sumir do site publicado. A §2.4 mostra o arquivo de uma linha que desliga isso.

1.3 O que muda em relação ao Live Server¶

No Capítulo 01 você abriu o site com o Live Server, em http://127.0.0.1:5500/site-evento/index.html. Na publicação, quatro coisas mudam — e todas viram bug se você não souber:

1. A raiz do site muda. No Live Server a raiz é a pasta que você abriu no VS Code. No GitHub Pages de projeto, o site vive dentro de /site-evento/, e a raiz do domínio pertence a outro site. É a §3 inteira.
2. O sistema de arquivos diferencia maiúsculas. Windows e macOS, por padrão, tratam Logo.png e logo.png como o mesmo arquivo. O servidor Linux da CDN não. Um <img src="img/Logo.png"> que funciona na sua máquina devolve 404 no ar.
3. Existe cache. O Live Server manda o navegador nunca guardar nada. A CDN faz o contrário: guarda tudo o que puder, por minutos ou meses. É a §8.
4. Só vai para o ar o que está no Git. Se img/logo.png está no .gitignore, ou se você esqueceu de commitar, ele simplesmente não existe do lado de lá.

🔬 Investigue Rode curl -I https://weblab.aprendabit.com e curl -I https://github.com e compare os cabeçalhos das duas respostas. Procure server, cache-control, content-type e etag. Depois rode curl -I https://weblab.aprendabit.com/pagina-que-nao-existe e anote o código de status. O -I pede só os cabeçalhos (método HEAD) — é a forma mais rápida de saber quem está servindo um site e como ele manda o navegador guardar as respostas.

2. GitHub Pages¶

2.1 Os dois tipos de site¶

O GitHub Pages publica o conteúdo de um repositório em um endereço *.github.io. Existem dois formatos, e a diferença entre eles é a origem da maior parte dos problemas deste capítulo:

Você tem um site de usuário por conta e quantos sites de projeto quiser. O site-evento é um site de projeto: ele vai morar em https://ana-souza.github.io/site-evento/ — dentro de um subcaminho, e não na raiz do domínio.

Guarde isso: o seu site não está na raiz. A §3 existe por causa desta frase.

2.2 Publicando pelo painel¶

O caminho oficial tem cinco cliques:

1. Abra o repositório no GitHub (gh repo view --web faz isso do terminal).
2. Settings (aba do topo, à direita) → Pages (menu da esquerda, seção Code and automation).
3. Em Build and deployment → Source, escolha Deploy from a branch.
4. Em Branch, escolha main e a pasta / (root). Clique em Save.
5. Espere. Volte para a aba Actions do repositório: existe uma execução chamada pages build and deployment. Quando ela ficar verde, o site está no ar.

A caixa de Branch oferece duas pastas: / (root) e /docs. Use / (root) quando o index.html está na raiz do repositório — é o caso do site-evento. Use /docs quando o site é só uma parte de um repositório maior (documentação de uma API, por exemplo).

A opção GitHub Actions, no mesmo menu Source, serve para sites que precisam ser construídos antes de publicar — um projeto Vite do Nível 3, por exemplo, em que o que vai ao ar é a pasta dist/, e não os fontes. Esse é o assunto do Capítulo 09; aqui, o site já está pronto no repositório.

⚠️ Atenção O GitHub Pages é gratuito para repositórios públicos. Em repositório privado, ele exige uma conta paga. Neste projeto o repositório é público de qualquer jeito, então isso não te afeta — mas não coloque no site-evento nada que você não mostraria a qualquer pessoa. Publicar é publicar.

2.3 Publicando pelo terminal, com o gh¶

Tudo o que o painel faz, a API do GitHub também faz — e o gh api fala com ela. Dentro da pasta do repositório, os marcadores {owner} e {repo} são preenchidos sozinhos com o repositório atual:

# Liga o Pages, servindo a raiz da branch main
gh api --method POST repos/{owner}/{repo}/pages \
  -f "source[branch]=main" \
  -f "source[path]=/"

A resposta é um JSON com a configuração criada. Para acompanhar o estado sem abrir o navegador:

# Estado atual, URL pública e origem da publicação
gh api repos/{owner}/{repo}/pages --jq '{status: .status, url: .html_url, branch: .source.branch}'

# Última construção: status e mensagem de erro, se houver
gh api repos/{owner}/{repo}/pages/builds/latest --jq '{status: .status, erro: .error.message}'

O campo status passa por building e termina em built. Se der errored, a mensagem em .error.message diz o motivo (quase sempre uma sintaxe que o Jekyll não engoliu — veja a §2.4).

Se você mudar a configuração depois, o verbo é PUT, não POST:

# Trocar a pasta publicada de / para /docs
gh api --method PUT repos/{owner}/{repo}/pages \
  -f "source[branch]=main" \
  -f "source[path]=/docs"

# Pedir uma reconstrução manual (útil quando a publicação travou)
gh api --method POST repos/{owner}/{repo}/pages/builds

Saber fazer isso pelo terminal não é frescura: é o que permite automatizar a criação de um projeto inteiro em um script, como no Boss do Capítulo 02, e é a mesma API que o GitHub Actions usa no Capítulo 09.

2.4 As três manias do GitHub Pages¶

Jekyll come pastas com _. Por padrão, o Pages processa o site com o Jekyll antes de publicar, e o Jekyll trata pastas iniciadas por sublinhado como pastas de trabalho dele — elas não vão para o site. Um projeto Vite gera _assets/ ou nomes parecidos, e o resultado é um site sem CSS e sem JS. A solução é um arquivo vazio na raiz do site:

touch .nojekyll
git add .nojekyll
git commit -m "Desliga o processamento Jekyll no GitHub Pages"
git push

Crie esse arquivo sempre. Ele não atrapalha nada e evita uma tarde de depuração.

O index.html manda. Se não existe index.html na pasta publicada, o Pages mostra o README.md renderizado — e o estudante jura que "publicou errado". Não publicou: publicou uma pasta sem página inicial.

Existem limites, e eles são suaves. O site publicado deve ficar abaixo de 1 GB, a banda mensal recomendada é de 100 GB e há um limite de dez construções por hora. Nenhum projeto de estudo chega perto disso, mas vale saber que existe — e que a documentação oficial é a fonte a conferir, porque os números mudam.

📌 Vale gravar "Um site estático pode ter formulário de login?" Não com validação de verdade: qualquer verificação feita em JavaScript no navegador é lida e burlada por quem abre o DevTools. Autenticação exige servidor. Um site estático pode ter o formulário; a verificação precisa acontecer do outro lado.

3. Caminhos absolutos e relativos: o bug que aparece só depois de publicar¶

Este é o problema anunciado no Capítulo 01, e ele merece a seção mais longa deste capítulo. O sintoma é sempre o mesmo: na sua máquina o site está perfeito; publicado, ele aparece sem estilo, sem imagens e sem JavaScript, como um documento de texto dos anos 90.

3.1 Os três tipos de caminho¶

Todo href, src e url() do seu código é resolvido pelo navegador contra a URL da página atual. Há três formas de escrever:

A confusão de nome atrapalha: muita gente chama /css/estilo.css de "caminho absoluto". Ele é absoluto dentro do domínio — e é exatamente por isso que ele quebra quando o domínio não é seu inteiro.

3.2 Onde cada um vai parar¶

Suponha a página https://ana-souza.github.io/site-evento/programacao.html. Veja para onde o navegador manda cada requisição:

Na sua máquina, com o Live Server servindo a pasta site-evento como raiz, /css/estilo.css resolve para http://127.0.0.1:5500/css/estilo.css e funciona. É a mesma linha, com dois destinos diferentes. Por isso o bug só aparece depois do git push.

A regra prática para sites publicados em subcaminho é curta: nada de barra no começo. Use caminhos relativos ao documento em todo o HTML, no CSS e no JavaScript.

🔬 Investigue Abra o site-evento no Live Server. No index.html, troque href="css/estilo.css" por href="/css/estilo.css" e recarregue: continua funcionando. Agora abra o DevTools → Network, recarregue e clique na linha do estilo.css: leia a Request URL completa. Some /site-evento mentalmente à frente do host e você acaba de simular o que vai acontecer no ar. Desfaça a mudança.

3.3 O detalhe da barra final¶

Existe uma armadilha extra, e ela pega gente experiente. Compare:

https://ana-souza.github.io/site-evento/     →  a pasta é /site-evento/
https://ana-souza.github.io/site-evento      →  a "pasta" é /

Sem a barra final, o navegador considera que site-evento é um arquivo e resolve css/estilo.css como /css/estilo.css. O GitHub Pages e a Netlify normalmente redirecionam a URL sem barra para a URL com barra (301), e o problema desaparece — mas um servidor mal configurado não redireciona, e aí você tem um site quebrado só quando o link vem sem a barra.

Duas consequências práticas: ao divulgar o endereço, inclua a barra final; e, ao linkar uma pasta dentro do seu site, escreva <a href="blog/">, não <a href="blog">.

3.4 Páginas em subpastas mudam a conta¶

Caminho relativo ao documento depende da profundidade da página. Se você criar blog/post-1.html, o css/estilo.css escrito lá dentro resolve para /site-evento/blog/css/estilo.css — que não existe. De dentro de uma subpasta, o caminho correto é ../css/estilo.css.

Enquanto o site é plano (todas as páginas na raiz, como o site-evento), isso não aparece. Quando o site cresce, há três saídas:

1. Contar os ../ em cada página. Funciona, é chato e quebra quando você move um arquivo.
2. Usar <base>. Uma única tag no <head> redefine a base de todos os caminhos relativos daquele documento:

blog/post-1.html

<head>
  <meta charset="UTF-8">
  <base href="/site-evento/">
  <link rel="stylesheet" href="css/estilo.css">
</head>

Com essa <base>, css/estilo.css resolve para /site-evento/css/estilo.css de qualquer profundidade. O preço: a <base> afeta tudo, inclusive links de âncora (href="#a03-programacao" passa a apontar para /site-evento/#programacao, o que muda a página) e requisições de JavaScript. Use com consciência, e sempre com a barra final.

3. Deixar o construtor resolver. É o que Vite e companhia fazem: você declara a base uma vez e a ferramenta reescreve todos os caminhos no build.

vite.config.js

import { defineConfig } from 'vite'

export default defineConfig({
  // O site será servido em https://<usuario>.github.io/unieventos-web/
  // Sem esta linha, o Vite gera caminhos começando com / e o site publica quebrado.
  base: '/unieventos-web/'
})

Também dá para passar a base na linha de comando, sem tocar no arquivo — é o que o workflow do Capítulo 09 faz:

npm run build -- --base=/unieventos-web/

E, no código Vue/JS do projeto, o valor fica disponível em import.meta.env.BASE_URL, para montar caminhos de imagens dinâmicas sem chutar prefixo.

💡 Dica Antes de publicar, cace os caminhos com barra inicial em todo o projeto de uma vez:

bash grep -rn 'href="/\|src="/\|url(/' --include='*.html' --include='*.css' --include='*.js' .

Cada linha que aparecer é um candidato a 404 no ar. As exceções legítimas são URLs completas (https://…), uma <base href> deliberada e os caminhos dentro do 404.html, explicados na §5.

3.5 Maiúsculas contam¶

O servidor da CDN roda Linux e diferencia maiúsculas de minúsculas. img/Logo.png e img/logo.png são dois arquivos distintos para ele — mas o mesmo arquivo para o Windows e para o macOS com formatação padrão. Resultado: imagem que aparece na sua máquina e some no ar, sem erro nenhum além de um 404 no console.

Padronize tudo em minúsculas, sem acento e sem espaço: img/logo-semana-academica.png. Para corrigir um arquivo já versionado em um sistema que ignora maiúsculas, o Git precisa de dois passos, senão ele não percebe a mudança:

git mv img/Logo.png img/temporario.png
git mv img/temporario.png img/logo.png
git commit -m "Padroniza o nome do logo em minusculas"

4. Favicon: o 404 que o Capítulo 01 deixou pendente¶

4.1 Por que ele dá 404 sozinho¶

Todo navegador, ao abrir qualquer página, pede automaticamente /favicon.ico na raiz do domínio — mesmo que você nunca tenha escrito uma linha sobre isso. No Live Server, isso vira um 404 inofensivo no console. No GitHub Pages de projeto, é pior: o pedido vai para https://ana-souza.github.io/favicon.ico — a raiz do domínio, que pertence ao site de usuário, e não ao seu repositório de projeto. Colocar o favicon.ico na raiz do repositório não faz o navegador encontrá-lo sozinho nesse caso.

A solução é declarar o ícone explicitamente com <link rel="icon">, usando caminho relativo. Aí o navegador para de adivinhar.

4.2 O conjunto que resolve na prática¶

Três arquivos cobrem tudo o que importa hoje: um .ico de 32×32 para navegadores antigos e para a aba, um SVG que escala em qualquer tamanho, e um PNG de 180×180 para o ícone de tela inicial do iOS.

index.html (dentro do <head>, nas cinco páginas)

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Semana Acadêmica de Sistemas de Informação</title>

  <!-- Ícone clássico, para a aba e para navegadores antigos -->
  <link rel="icon" href="favicon.ico" sizes="32x32">
  <!-- Ícone vetorial: escala perfeito em qualquer densidade de tela -->
  <link rel="icon" href="img/favicon.svg" type="image/svg+xml">
  <!-- Ícone do atalho na tela inicial do iOS (180x180) -->
  <link rel="apple-touch-icon" href="img/apple-touch-icon.png">
  <!-- Metadados de aplicativo: nome curto, cores e ícones grandes -->
  <link rel="manifest" href="site.webmanifest">
  <meta name="theme-color" content="#0b3d2e">

  <link rel="stylesheet" href="css/estilo.css">
</head>

Repare que nenhum caminho começa com barra. É a regra da §3 aplicada aos ícones.

site.webmanifest

{
  "name": "Semana Acadêmica de Sistemas de Informação",
  "short_name": "Semana Acadêmica",
  "start_url": "./",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0b3d2e",
  "icons": [
    { "src": "img/icone-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "img/icone-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Os caminhos dentro do manifesto são resolvidos em relação ao próprio manifesto, e não à página. Como o site.webmanifest está na raiz do site, img/icone-192.png funciona; start_url: "./" mantém o atalho apontando para o subcaminho certo.

4.3 Fazendo os arquivos¶

Comece por um SVG quadrado simples — ícone bom é ícone que se reconhece a 16 pixels. Um monograma resolve:

img/favicon.svg

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Semana Academica">
  <rect width="64" height="64" rx="12" fill="#0b3d2e"/>
  <text x="32" y="43" font-family="system-ui, sans-serif" font-size="34"
        font-weight="700" fill="#ffffff" text-anchor="middle">SA</text>
</svg>

Para gerar os PNG e o .ico a partir de uma imagem quadrada de pelo menos 512 pixels, o ImageMagick resolve em três linhas (Ubuntu: sudo apt install imagemagick):

magick img/logo-512.png -resize 192x192 img/icone-192.png
magick img/logo-512.png -resize 180x180 img/apple-touch-icon.png
magick img/logo-512.png -resize 32x32 favicon.ico

Sem ImageMagick, o https://realfavicongenerator.net faz o mesmo pelo navegador e entrega um .zip com todos os tamanhos e o trecho de HTML pronto.

🧠 Você sabia? O favicon.ico é uma herança direta do Internet Explorer 5, de 1999. A Microsoft inventou o recurso para mostrar um ícone quando o usuário adicionava a página aos favoritos — daí o nome, favorite icon. O formato .ico é da própria Microsoft e guarda várias resoluções dentro do mesmo arquivo. A convenção de pedir /favicon.ico automaticamente pegou tão bem que, um quarto de século depois, todo navegador do planeta ainda faz esse pedido em toda página que abre — inclusive na sua.

5. A página 404¶

Quando alguém digita errado ou clica em um link velho, o servidor devolve o código 404 Not Found e uma página feia e genérica. Você pode substituí-la por uma sua: basta um arquivo 404.html na raiz do site publicado. GitHub Pages, Netlify, Vercel e Cloudflare Pages usam esse arquivo automaticamente, sem configuração.

404.html

<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Página não encontrada — Semana Acadêmica</title>
  <link rel="icon" href="/site-evento/favicon.ico" sizes="32x32">
  <link rel="stylesheet" href="/site-evento/css/estilo.css">
</head>
<body>
  <main class="erro">
    <h1>404 — esta página não existe</h1>
    <p>
      O endereço que você abriu não corresponde a nenhuma página do site da
      Semana Acadêmica. Talvez o link esteja desatualizado.
    </p>
    <ul>
      <li><a href="/site-evento/">Ir para a página inicial</a></li>
      <li><a href="/site-evento/programacao.html">Ver a programação</a></li>
      <li><a href="/site-evento/contato.html">Falar com a organização</a></li>
    </ul>
  </main>
</body>
</html>

Aqui a regra da §3 se inverte, e por um bom motivo. O 404.html é servido em resposta a qualquer endereço inexistente: /site-evento/programacao/dia-1/, /site-evento/a/b/c/d. A profundidade é imprevisível, então caminho relativo ao documento resolveria para lugares diferentes a cada erro — e a página de erro apareceria sem CSS, o que é uma ironia difícil de justificar. Por isso, e só no 404.html, use caminho relativo à raiz incluindo o nome do repositório: /site-evento/css/estilo.css.

Se um dia o site ganhar domínio próprio (Capítulo 04), ele passa a viver na raiz e esses caminhos viram /css/estilo.css. Deixe um comentário no arquivo lembrando disso.

💡 Dica Aplicações de página única (o UniEventos do Nível 3, com vue-router) precisam que toda URL devolva o index.html, para o roteador do navegador decidir o que mostrar. Na Netlify, na Vercel e na Cloudflare Pages isso se declara em uma regra de reescrita (§6.3). O GitHub Pages não tem reescrita — o truque conhecido é publicar uma cópia do index.html com o nome 404.html: o servidor devolve a cópia (com status 404, que os buscadores não gostam, mas o navegador ignora) e o roteador assume dali. Funciona; não é elegante.

6. Netlify¶

A Netlify resolve as mesmas necessidades do GitHub Pages com mais recursos: pré-visualização de cada pull request, redirecionamentos, cabeçalhos personalizados, formulários e funções. Para o Café Cerrado estático do Nível 2, ela é a escolha natural.

6.1 Arrastar e soltar: publicando em quarenta segundos¶

O caminho mais rápido do mundo para colocar um site no ar:

1. Abra https://app.netlify.com/drop (logado).
2. Arraste a pasta do site (não um .zip, não os arquivos soltos) para a área indicada.
3. Pronto. Em segundos você recebe uma URL como https://elegant-pasteur-1a2b3c.netlify.app.
4. Em Site configuration → Site details → Change site name, troque para cafe-cerrado. A URL vira https://cafe-cerrado.netlify.app.

Use isso para mostrar um trabalho para alguém em cinco minutos, e só. O problema é óbvio: publicar de novo exige arrastar de novo, não há histórico, e o que está no ar não tem relação com o que está no Git. É publicação descartável.

6.2 A partir do Git: o jeito que se usa de verdade¶

1. No painel, Add new site → Import an existing project → Deploy with GitHub. Autorize o acesso ao repositório cafe-cerrado.
2. A Netlify pergunta três coisas: - Branch to deploy: main. - Build command: vazio, para um site sem construção (HTML/CSS/JS puro). Para um projeto Vite, npm run build. - Publish directory: . para um site puro (a raiz do repositório); dist para um projeto Vite.
3. Deploy site. A Netlify clona o repositório, roda o build (se houver) e publica a pasta indicada.

A partir daí, todo git push na main publica automaticamente. E cada pull request aberto ganha um Deploy Preview: uma URL temporária com aquela versão do site, que a Netlify comenta no próprio PR. É a peça que faltava na revisão de código do Capítulo 02 — o revisor deixa de imaginar como ficou e clica para ver.

🧠 Você sabia? Quem popularizou o nome Jamstack foi a Netlify, por volta de 2015: JavaScript, APIs e Markup. A ideia era dar nome a uma arquitetura em que o HTML é gerado antes (não a cada requisição), servido por CDN, e tudo que é dinâmico chega por chamadas a APIs feitas no navegador. É exatamente a arquitetura dos seus três projetos das trilhas quando ficam prontos: front estático publicado em CDN, conversando com uma API própria.

6.3 netlify.toml: a configuração versionada¶

Configuração feita por cliques no painel não vai para o Git, não é revisada em pull request e some quando o site é recriado. A alternativa é um arquivo na raiz do repositório:

netlify.toml

# Configuração do site Café Cerrado na Netlify.
# Este arquivo tem prioridade sobre o que estiver configurado no painel.

[build]
  # Pasta que vai ao ar. "." = a raiz do repositório (site sem etapa de build).
  publish = "."
  # Sem comando de build: o site é HTML/CSS/JS puro.
  command = ""

[build.environment]
  NODE_VERSION = "22"

# Endereço antigo, divulgado no primeiro cardápio impresso: redireciona de vez.
[[redirects]]
  from = "/menu.html"
  to = "/cardapio.html"
  status = 301
  force = true

# Cabeçalhos de segurança em todas as respostas.
[[headers]]
  for = "/*"
  [headers.values]
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

# Imagens e fontes mudam pouco: cache longo (uma semana).
[[headers]]
  for = "/img/*"
  [headers.values]
    Cache-Control = "public, max-age=604800"

Três blocos que você vai reusar em quase todo projeto:

• [build] define o que é construído e o que é publicado. É o bloco que resolve o erro "Page Not Found" logo depois do primeiro deploy: quase sempre o publish aponta para a pasta errada.
• [[redirects]] cria redirecionamentos. Com status = 200 em vez de 301, o redirecionamento vira reescrita: a URL na barra continua a mesma e o conteúdo vem de outro arquivo. É assim que se serve uma SPA:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

• [[headers]] adiciona cabeçalhos de resposta — segurança, cache, o que você precisar. Cada bloco casa com um padrão de caminho.

A Netlify também aceita os arquivos de texto _redirects e _headers na pasta publicada, com a mesma função e sintaxe mais enxuta (a Cloudflare Pages entende os mesmos dois arquivos). Prefira o netlify.toml: um arquivo só, comentado, e com o build junto.

6.4 A CLI da Netlify¶

Para quem prefere o terminal, ou para automatizar depois:

# Autentica pelo navegador (uma vez por máquina)
npx --yes netlify-cli login

# Liga a pasta atual a um site já existente na sua conta
npx --yes netlify-cli link

# Publicação de rascunho: gera uma URL temporária para conferir
npx --yes netlify-cli deploy --dir=.

# Publicação definitiva, no endereço oficial do site
npx --yes netlify-cli deploy --prod --dir=. --message "Cardapio com fotos novas"

# Estado do site ligado a esta pasta
npx --yes netlify-cli status

O deploy sem --prod é um recurso subestimado: ele publica uma URL de rascunho que você abre, confere e só então promove. É a versão em produção do "olha antes de mandar".

7. Vercel e Cloudflare Pages, em resumo¶

As quatro plataformas fazem a mesma coisa básica. As diferenças aparecem no que vem junto:

Vercel. Pelo painel: https://vercel.com/new → importar o repositório do GitHub → ela detecta o framework, sugere o comando de build e a pasta de saída → Deploy. Pelo terminal, na pasta do projeto:

npx --yes vercel login
npx --yes vercel          # publica uma URL de pré-visualização
npx --yes vercel --prod   # publica no endereço de produção

A configuração versionada é o vercel.json:

vercel.json

{
  "cleanUrls": true,
  "redirects": [
    { "source": "/menu.html", "destination": "/cardapio.html", "permanent": true }
  ],
  "headers": [
    {
      "source": "/img/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=604800" }
      ]
    }
  ]
}

O cleanUrls: true faz /cardapio servir cardapio.html, sem a extensão na barra de endereço.

Cloudflare Pages. Pelo painel: Workers & Pages → Create → Pages → Connect to Git, escolher o repositório, informar comando de build e diretório de saída. Pelo terminal, com o wrangler:

npx --yes wrangler login
npx --yes wrangler pages deploy . --project-name=site-evento

Ela lê os mesmos arquivos _redirects e _headers da Netlify, o que torna a migração entre as duas quase indolor.

Para os projetos usados nesta trilha, a recomendação é simples: GitHub Pages para o site-evento (é onde o código já está) e Netlify para o cafe-cerrado (você vai precisar de redirecionamento e de cabeçalhos). Publicar o mesmo site em mais de uma plataforma, para comparar de verdade, é um ótimo exercício — e é o desafio ⭐⭐.

8. Cache: por que o site velho insiste em aparecer¶

8.1 Quem guarda o quê¶

Você corrigiu o CSS, fez git push, a publicação ficou verde — e o site continua igual. Antes de duvidar da plataforma, saiba que há quatro camadas de cache entre o seu arquivo e o olho de quem visita:

seu arquivo ─► CDN da plataforma ─► proxy do provedor ─► cache do navegador ─► tela

Cada camada guarda uma cópia pelo tempo que o cabeçalho cache-control autorizar. Leia esse cabeçalho com curl:

curl -I https://ana-souza.github.io/site-evento/
curl -I https://ana-souza.github.io/site-evento/css/estilo.css

Interessam quatro cabeçalhos da resposta:

Com etag, o navegador faz uma requisição condicional na próxima visita: manda If-None-Match e recebe 304 Not Modified (resposta vazia, rápida) se nada mudou. Com max-age ainda válido, ele nem pergunta.

8.2 Como forçar a versão nova¶

Na sua máquina, para conferir se a correção subiu:

Para os visitantes, nada disso serve: você não pode pedir a cada pessoa que aperte Ctrl+F5. A solução é mudar o nome do arquivo sempre que o conteúdo muda, para que o navegador seja obrigado a pedir de novo:

<link rel="stylesheet" href="css/estilo.css?v=3">

Cada mudança relevante no CSS vira ?v=4, ?v=5. É rústico, mas funciona e é suficiente para um site escrito à mão. Ferramentas de build fazem isso melhor, colocando um resumo do conteúdo no nome (estilo-8f3a91c2.css): mudou um byte, muda o nome, o cache antigo fica órfão e ninguém precisa lembrar de nada.

A partir daí vale a regra de ouro do cache:

• HTML: cache curto ou nenhum, porque é ele que aponta para os outros arquivos.
• CSS, JS e imagens com nome versionado: cache longo (max-age=31536000, immutable), porque o nome garante que o conteúdo nunca muda.

🔎 Por baixo do capô 304 Not Modified é a resposta mais barata do HTTP: o servidor manda só cabeçalhos, sem corpo. O navegador guardou o etag da visita anterior, reenvia em If-None-Match, e o servidor compara. Se bate, 304 e o navegador reaproveita a cópia local. Isso significa que existem duas economias distintas: com max-age válido não há requisição nenhuma (economia de tempo e de banda); com max-age vencido mas etag igual há requisição, mas sem download (economia só de banda). Na aba Network, a coluna Size mostra (disk cache) no primeiro caso e 304 no segundo.

9. Medindo o site publicado com o Lighthouse¶

Site no ar não é site pronto. O Lighthouse abre a sua página em condições controladas (rede e processador simulados de celular médio) e devolve nota de 0 a 100 em quatro categorias: Performance, Acessibilidade, Práticas recomendadas e SEO.

Pelo navegador: DevTools → aba Lighthouse → modo Navigation, dispositivo Mobile, marcar as quatro categorias → Analyze page load. Faça isso em uma janela anônima: extensões do navegador injetam scripts e derrubam a nota sem culpa do seu site.

Pelo terminal, o que é útil quando você quer guardar o relatório no repositório:

npx --yes lighthouse https://ana-souza.github.io/site-evento/ \
  --output html --output-path ./relatorio-antes.html --view

O --view abre o relatório no navegador ao terminar. Para simular desktop em vez de celular, acrescente --preset=desktop. Uma terceira via, sem instalar nada, é o https://pagespeed.web.dev: ele roda o mesmo Lighthouse nos servidores do Google.

As correções que mais rendem em um site estático típico de estudo, em ordem de retorno:

Anote as quatro notas antes de mexer em qualquer coisa. Sem o número inicial, "melhorou" é opinião.

🚀 Passo a passo — o site do evento no GitHub Pages e o Café Cerrado na Netlify¶

O que vai ao ar: o site-evento (Nível 1) em https://<usuario>.github.io/site-evento/, com favicon e página 404, e o cafe-cerrado (Nível 2) em https://cafe-cerrado.netlify.app, publicado a partir do Git com netlify.toml. Troque ana-souza pelo seu usuário do GitHub. Faça na ordem.

Passo 1 — Confirme o ponto de partida¶

cd ~/weblab/site-evento
git status
gh repo view --json name,visibility,url

Resultado esperado: nothing to commit, working tree clean, visibilidade PUBLIC e a URL do repositório. Se git status listar arquivos pendentes, commite e dê push antes de continuar — o Pages publica o que está no GitHub, não o que está no seu disco.

Passo 2 — Cace os caminhos que vão quebrar¶

grep -rn 'href="/\|src="/\|url(/' --include='*.html' --include='*.css' --include='*.js' .

Cada resultado é um caminho relativo à raiz do domínio. Troque todos por relativos ao documento: /css/estilo.css vira css/estilo.css, /img/logo.png vira img/logo.png. Confira também os nomes dos arquivos de imagem: tudo minúsculo, sem acento e sem espaço (§3.5).

ls -1 img/
git add -A
git commit -m "Troca caminhos absolutos por relativos para publicar em subcaminho"

Passo 3 — Favicon, manifesto e 404¶

Crie img/favicon.svg, favicon.ico, img/apple-touch-icon.png, img/icone-192.png e img/icone-512.png com os comandos da §4.3 (ou pelo gerador online). Depois:

1. Cole o bloco de <link rel="icon"> da §4.2 no <head> das cinco páginas.
2. Crie o site.webmanifest da §4.2 na raiz.
3. Crie o 404.html da §5, com os caminhos começando em /site-evento/.
4. Crie o arquivo que desliga o Jekyll:

touch .nojekyll
git add -A
git commit -m "Adiciona favicon, manifesto, pagina 404 e .nojekyll"
git push

Passo 4 — Ligue o GitHub Pages¶

Pelo painel: Settings → Pages → Source: Deploy from a branch → Branch: main / (root) → Save.

Ou, sem sair do terminal:

gh api --method POST repos/{owner}/{repo}/pages \
  -f "source[branch]=main" \
  -f "source[path]=/"

Acompanhe a publicação:

gh api repos/{owner}/{repo}/pages --jq '{status: .status, url: .html_url}'

Repita até status virar built. Costuma levar menos de um minuto na primeira vez.

Passo 5 — Confira o que foi publicado¶

curl -I https://ana-souza.github.io/site-evento/
curl -I https://ana-souza.github.io/site-evento/css/estilo.css
curl -I https://ana-souza.github.io/site-evento/pagina-inexistente

Resultado esperado: HTTP/2 200 com server: GitHub.com nas duas primeiras e HTTP/2 404 na terceira, com content-type: text/html. Depois abra a URL no navegador em janela anônima, com o DevTools na aba Network: nenhuma linha em vermelho, e a linha do favicon.ico com status 200 apontando para /site-evento/favicon.ico.

Passo 6 — Conserte o que ainda estiver 404¶

Se aparecer linha vermelha, clique nela e leia a Request URL completa. Praticamente sempre é uma destas três causas: caminho com barra inicial que escapou do grep (§3.2), nome de arquivo com maiúscula (§3.5) ou arquivo que não foi commitado. Corrija, git push e recarregue com Ctrl+F5.

Passo 7 — Café Cerrado na Netlify, versão descartável¶

Abra https://app.netlify.com/drop e arraste a pasta cafe-cerrado inteira. Anote a URL sorteada e abra o site. Isso leva menos de um minuto e serve para você ver a diferença para o passo seguinte — não é a forma que você vai usar daqui para a frente.

Passo 8 — Café Cerrado na Netlify, a partir do Git¶

Primeiro, o arquivo de configuração no repositório:

cafe-cerrado/netlify.toml

[build]
  publish = "."
  command = ""

[build.environment]
  NODE_VERSION = "22"

[[headers]]
  for = "/*"
  [headers.values]
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

[[headers]]
  for = "/img/*"
  [headers.values]
    Cache-Control = "public, max-age=604800"

cd ~/weblab/cafe-cerrado
git add netlify.toml
git commit -m "Configura publicacao e cabecalhos na Netlify"
git push

No painel da Netlify: Add new site → Import an existing project → Deploy with GitHub → cafe-cerrado → Deploy. Como o netlify.toml já define publish e command, aceite o que o formulário sugerir. Quando terminar, vá em Site configuration → Site details → Change site name e troque para cafe-cerrado.

Agora prove que o deploy contínuo funciona: mude uma linha visível do site (o título do cardápio, por exemplo), commite, dê push e acompanhe em Deploys no painel. A nova versão sobe sozinha.

Passo 9 — Meça os dois¶

npx --yes lighthouse https://ana-souza.github.io/site-evento/ \
  --output html --output-path ./relatorio-site-evento.html --view

npx --yes lighthouse https://cafe-cerrado.netlify.app/ \
  --output html --output-path ./relatorio-cafe-cerrado.html --view

Anote as quatro notas de cada um em um arquivo medicoes.md e escolha três correções da tabela da §9 para aplicar hoje.

Como conferir¶

curl -I https://ana-souza.github.io/site-evento/
curl -s https://ana-souza.github.io/site-evento/ | grep -c 'rel="icon"'
curl -I https://cafe-cerrado.netlify.app/img/xicara.png | grep -i cache-control
curl -I https://cafe-cerrado.netlify.app/pagina-inexistente

Resultado esperado:

• o primeiro curl devolve HTTP/2 200 com server: GitHub.com;
• o grep -c conta 2 (o .ico e o SVG) — se contar 0, o <link rel="icon"> não subiu;
• o terceiro mostra cache-control: public, max-age=604800, provando que o netlify.toml está valendo;
• o quarto devolve 404, servindo a sua página de erro;
• nos dois sites, o DevTools em janela anônima não mostra nenhuma requisição em vermelho, e o ícone aparece na aba do navegador.

🧪 Laboratório¶

Nível A — Fixação¶

A1. A página https://ana-souza.github.io/site-evento/palestrantes.html contém <img src="../img/foto.png">. Escreva a URL exata que o navegador vai pedir. Ela existe? Qual seria a forma correta?

A2. Um repositório se chama portfolio e pertence ao usuário joao-silva. Qual é a URL do site de projeto? E se ele renomear o repositório para joao-silva.github.io, qual passa a ser a URL?

A3. Preveja antes de rodar: em curl -I de um CSS recém-publicado no GitHub Pages, quais destes cabeçalhos você espera encontrar — cache-control, etag, content-type, set-cookie? Rode e confirme. Por que um deles não faz sentido em hospedagem estática?

A4. Explique em duas linhas por que colocar favicon.ico na raiz do repositório não basta em um site de projeto do GitHub Pages, mas basta em um site de usuário.

A5. Complete o netlify.toml para um projeto Vite cujo index.html gerado vai para dist/: qual é o publish, qual é o command e qual bloco você acrescenta para que uma SPA responda em qualquer rota?

A6. Verdadeiro ou falso, justificando: "trocar estilo.css por estilo.css?v=2 no HTML faz o servidor mandar um arquivo diferente". O que exatamente muda?

Nível B — Aplicação¶

B1. Quebre e conserte. No site-evento já publicado, crie a branch teste-caminhos, troque todos os href/src do index.html para a forma com barra inicial, commite e publique essa branch no Pages (mude o Branch em Settings → Pages). Documente o estrago e desfaça.

Resultado esperado: um arquivo caminhos.md com uma captura da aba Network mostrando os 404, a Request URL de dois recursos quebrados, a explicação de por que na sua máquina funcionava, e o git revert do commit que quebrou.

B2. Página 404 que se defende. Escreva um 404.html para o seu projeto autoral que funcione em qualquer profundidade de URL e que ofereça ajuda de verdade: os três destinos mais prováveis e um campo de busca que leve para a página inicial com o termo na query string.

Resultado esperado: abrir https://<seu-site>/a/b/c/d mostra a sua página com CSS aplicado, e curl -I na mesma URL devolve 404. A página passa no Lighthouse em Acessibilidade com nota igual ou maior que a da home.

B3. O mesmo site, duas plataformas. Publique o site-evento também na Netlify a partir do Git, sem desligar o GitHub Pages, e compare as duas hospedagens.

Resultado esperado: uma tabela em comparacao.md com quatro linhas (URL, server, cache-control do HTML, nota de Performance no Lighthouse) e as duas colunas de plataforma, mais um parágrafo dizendo qual você escolheria para o seu projeto autoral e por quê.

Nível C — Desafio¶

C1. Publicação sem cliques. Escreva um script publicar.sh que, rodado dentro de qualquer pasta de site estático não versionada, deixe o site no ar em uma URL do GitHub Pages: cria .nojekyll e .gitignore se não existirem, roda git init e o primeiro commit, cria o repositório remoto com gh repo create, faz push, liga o Pages via gh api, espera o status virar built consultando a API em laço, e imprime a URL final. Rodar o script duas vezes na mesma pasta não pode dar erro nem duplicar nada.

🏆 Desafios¶

🐛 Erros comuns¶

🏠 Para praticar depois da aula (1 h)¶

Publique o seu projeto autoral e deixe-o apresentável:

1. Garanta que o repositório está público e limpo (git status sem pendências) e que não há nenhum caminho com barra inicial fora do 404.html — prove com a saída do grep da §3.4 colada no relatório.
2. Publique no GitHub Pages (ou na Netlify, se o projeto precisar de redirecionamentos) e anote a URL completa, com barra final.
3. Adicione favicon (.ico + SVG), apple-touch-icon, site.webmanifest e 404.html, todos funcionando na URL publicada.
4. Rode o Lighthouse na URL pública e salve o relatório como relatorio-lighthouse.html no repositório.
5. Escreva no README.md uma seção Site publicado com: a URL clicável, a plataforma escolhida com uma linha de justificativa, e as quatro notas do Lighthouse.

Critério de pronto: a URL abre em janela anônima com todos os recursos carregando (nenhuma linha vermelha no DevTools), o ícone aparece na aba, um endereço inexistente devolve a sua página 404 com CSS aplicado, e o README.md do repositório mostra a URL e as notas.

Guarde no seu repositório: o link do repositório e a URL do site publicado. Nada de .zip.

✅ Está no ar quando…¶

• [ ] https://<seu-usuario>.github.io/site-evento/ abre em janela anônima, com estilo, imagens e o menu funcionando.
• [ ] curl -I https://<seu-usuario>.github.io/site-evento/ devolve HTTP/2 200 com server: GitHub.com.
• [ ] O DevTools → Network, com o cache desligado, não mostra nenhuma requisição em vermelho — inclusive a do favicon.
• [ ] O ícone aparece na aba do navegador e no atalho de tela inicial do celular.
• [ ] https://<seu-usuario>.github.io/site-evento/nao-existe mostra a sua página 404, com CSS, e curl -I confirma o status 404.
• [ ] O arquivo .nojekyll está no repositório.
• [ ] https://cafe-cerrado.netlify.app abre, e curl -I em uma imagem mostra o cache-control definido no netlify.toml.
• [ ] Um git push na main do cafe-cerrado publica a mudança sozinho, sem nenhum clique.
• [ ] Você tem, salvos no repositório, os relatórios do Lighthouse dos dois sites, e sabe dizer as quatro notas de cada um.
• [ ] Você explica, sem consultar, para onde /css/estilo.css resolve em https://usuario.github.io/site-evento/programacao.html, e por que na sua máquina isso funcionava.

📚 Para aprofundar¶

• GitHub Docs, "GitHub Pages" — https://docs.github.com/pt/pages — comece por "Criando um site do GitHub Pages" e "Configurando uma fonte de publicação"; é a referência oficial de tudo na §2.
• GitHub REST API, "Pages" — https://docs.github.com/pt/rest/pages — os endpoints usados com gh api na §2.3, com todos os campos da resposta.
• Netlify Docs — https://docs.netlify.com — leia "Get started", "File-based configuration" (o netlify.toml da §6.3) e "Redirects and rewrites".
• Netlify CLI — https://cli.netlify.com — todos os comandos, incluindo o deploy de rascunho da §6.4.
• Vercel Docs, "Projects" e "Configuring projects with vercel.json" — https://vercel.com/docs — o equivalente da Vercel ao netlify.toml.
• Cloudflare Pages — https://developers.cloudflare.com/pages/ — a seção "Get started" e a de _headers/_redirects.
• MDN, "Escolhendo entre URLs absolutas e relativas" — https://developer.mozilla.org/pt-BR/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL — a anatomia de uma URL, base de toda a §3.
• MDN, "<base>" — https://developer.mozilla.org/pt-BR/docs/Web/HTML/Element/base — e "<link rel="icon">" — https://developer.mozilla.org/pt-BR/docs/Web/HTML/Attributes/rel — as duas tags da §3.4 e da §4.2.
• MDN, "Cache-Control" — https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Headers/Cache-Control — e "HTTP caching" — a base da §8.
• web.dev, "Lighthouse" — https://developer.chrome.com/docs/lighthouse/ — o que cada categoria mede e como interpretar cada auditoria da §9.
• PageSpeed Insights — https://pagespeed.web.dev — o Lighthouse rodando nos servidores do Google, com dados de campo quando o site tem visitantes.
• MILETTO, Evandro M.; BERTAGNOLLI, Silvia C. Desenvolvimento de software II. Bookman — capítulo sobre publicação e implantação de aplicações web.

No próximo capítulo, o endereço deixa de ser sorteado pela plataforma: você registra um domínio, entende como um nome vira um IP, aponta evento.seudominio.dev para este mesmo site e coloca o cadeado do HTTPS na barra de endereço.

🎯 Objetivos de aprendizagem¶

Ao final deste capítulo você será capaz de:

• Explicar, etapa por etapa, como o navegador transforma evento.seudominio.dev em um endereço IP, e o que TTL e "propagação" significam de verdade.
• Registrar um domínio (.br no Registro.br ou genérico em outro registrador), ler um WHOIS e separar os três papéis: registrador, provedor de DNS e hospedagem.
• Criar registros A, AAAA, CNAME, TXT e MX, escolhendo o tipo certo para cada situação.
• Apontar um domínio ou subdomínio para GitHub Pages, Netlify, Vercel ou um VPS, e diagnosticar o resultado com dig, nslookup, host e dnschecker.org.
• Descrever o que um certificado TLS prova, como a cadeia de confiança funciona e como a Let's Encrypt emite e renova certificados pelo protocolo ACME.
• Forçar HTTPS, ativar HSTS e usar a Cloudflare como DNS e proxy escolhendo o modo SSL correto.
• Reconhecer e corrigir os erros clássicos: DNS_PROBE_FINISHED_NXDOMAIN, certificado de outro domínio e conteúdo misto.

📋 Pré-requisitos¶

• [ ] Site do evento acadêmico (Nível 1) publicado no GitHub Pages ou Netlify (Capítulo 03), acessível em https://<usuario>.github.io/<repositorio>/.
• [ ] Terminal com dig (Ubuntu/Debian: sudo apt install dnsutils; macOS: já vem instalado; Windows: use o WSL ou o nslookup, que já vem no sistema).
• [ ] curl instalado (curl --version).
• [ ] Um domínio próprio — opcional, mas recomendado. A §2 mostra opções baratas e gratuitas para quem ainda não tem.

No Capítulo 03 você publicou o site do evento em um endereço que a plataforma escolheu por você, algo como usuario.github.io/site-evento. Funciona, mas ninguém coloca isso num cartão de visita. Hoje o site ganha um nome próprio, com cadeado — e você entende tudo o que acontece entre a barra de endereço e o servidor.

🗺️ Roteiro¶

1. Como um nome vira um endereço IP¶

1.1 Anatomia de um nome¶

Leia um nome de domínio da direita para a esquerda. O nome completo de evento.seudominio.dev é, tecnicamente, evento.seudominio.dev. — com um ponto final que representa a raiz do DNS: