por Tiago Silva

Este guia registra a preparação de um computador para executar localmente um site desenvolvido com Jekyll.

O objetivo é deixar documentado o processo completo, desde a instalação do Ruby e das dependências necessárias até a execução do servidor local para visualizar e testar alterações antes da publicação.

Os exemplos utilizam PowerShell no Windows, considerando principalmente a configuração de um computador recém-formatado.

1. Pré-requisitos

Em um computador recém-formatado, instale:

O Ruby deve ser instalado com uma versão estável Ruby+Devkit. Durante a instalação, mantenha habilitada a opção que adiciona o Ruby ao PATH.

Ao final da instalação, execute a configuração do MSYS2/DevKit quando solicitado. Esse ambiente fornece ferramentas utilizadas por gems que precisam compilar extensões nativas.

Depois da instalação, feche todos os terminais abertos e inicie um novo PowerShell.

2. Verificar a instalação do Ruby

No terminal:

ruby --version
gem --version

Os dois comandos devem retornar suas respectivas versões.

Se o terminal informar que ruby ou gem não são reconhecidos, o Ruby ainda não está instalado corretamente ou seu diretório não foi adicionado ao PATH.

3. Instalar o Bundler

Com Ruby e RubyGems funcionando:

gem install bundler

Confirme a instalação:

bundle --version

4. Projeto Jekyll

Acesse o projeto que utilzia Jekyll:

cd C:\caminho\para\controlandoeletrons-site

A pasta correta deve conter, entre outros arquivos:

_config.yml
Gemfile
Gemfile.lock

5. Instalar as dependências do site

Na raiz do repositório:

bundle install

O Bundler utilizará o Gemfile e o Gemfile.lock para instalar as versões das gems esperadas pelo projeto.

Esse passo é necessário apenas na primeira execução, mas pode ser necessário novamente caso as dependências do projeto sejam alteradas.

6. Executar o site localmente

Na raiz do repositório:

bundle exec jekyll serve

Quando o build terminar, o Jekyll exibirá um endereço semelhante a:

http://127.0.0.1:4000/

O site pode então ser acessado pelo navegador em:

http://localhost:4000/

O processo permanece ativo no terminal enquanto o servidor local estiver em execução.

Para encerrá-lo:

Ctrl+C

7. Executar com atualização automática do navegador

Durante edição de páginas, estilos e conteúdo, prefira:

bundle exec jekyll serve --livereload

O Jekyll continuará recompilando o site quando detectar alterações nos arquivos e o LiveReload atualizará o navegador automaticamente quando aplicável.

8. Limpar e reconstruir o site

O Jekyll grava o resultado da geração em _site/ e também pode manter arquivos de cache. Durante alterações simples de texto, o servidor local normalmente recompila apenas o necessário. Entretanto, mudanças em permalinks, nomes de páginas, layouts, configurações ou caminhos de imagens podem deixar arquivos antigos no diretório gerado.

Nesses casos, interrompa o servidor local com Ctrl+C e, dentro de controlandoeletrons-site, limpe os arquivos gerados:

bundle exec jekyll clean

O comando remove _site/ e os caches do Jekyll. Ele não apaga os arquivos-fonte do site.

Depois, faça uma reconstrução completa usando a validação estrita do front matter:

bundle exec jekyll build --strict_front_matter

O --strict_front_matter interrompe o build quando existe um erro de sintaxe no YAML localizado entre os delimitadores --- de uma página ou publicação.

Após o build, execute o validador específico do site:

ruby scripts/validate_build.rb _site .

Esse script verifica, entre outras regras, campos obrigatórios, permalinks, capas, dimensões de imagens, metadados, páginas geradas e referências internas. Quando tudo estiver correto, a saída será semelhante a:

Build validado: 5 publicações e 9 páginas HTML.

O número de publicações e páginas varia conforme o conteúdo do site. Para limpar, reconstruir e validar em sequência:

bundle exec jekyll clean
bundle exec jekyll build --strict_front_matter
ruby scripts/validate_build.rb _site .

Depois da validação, o servidor de desenvolvimento pode ser iniciado novamente:

bundle exec jekyll serve --livereload

Esse procedimento é especialmente recomendado depois de:

  • alterar um permalink;
  • renomear ou mover páginas e publicações;
  • mudar caminhos de capas ou outras imagens;
  • editar _config.yml, layouts ou includes;
  • encontrar uma página antiga ainda presente em _site/;
  • receber um erro no validador durante o deploy.

Os arquivos dentro de _site/ são resultados do build e não devem ser editados manualmente. A correção deve ser feita nos arquivos-fonte e aplicada novamente por meio dos comandos acima. ```