Testar o site do GitHub Pages localmente com o Jekyll

Você pode criar o site do GitHub Pages localmente para visualizar e testar as alterações nele.

Quem pode usar esse recurso?

O GitHub Pages está disponível em repositórios públicos com o GitHub Free e o GitHub Free para organizações, e em repositórios públicos e privados com o GitHub Pro, o GitHub Team, o GitHub Enterprise Cloud e o GitHub Enterprise Server. Para mais informações, confira "Planos do GitHub".

O GitHub Pages agora usa o GitHub Actions para executar a compilação Jekyll. Ao usar uma ramificação como a origem da sua compilação, o GitHub Actions deverá estar habilitado em seu repositório se você quiser usar o fluxo de trabalho interno do Jekyll. Como alternativa, se o GitHub Actions não estiver disponível ou estiver desabilitado, adicionar um .nojekyll arquivo à raiz da ramificação de origem ignorará o processo de compilação do Jekyll e implantará o conteúdo diretamente. Para mais informações sobre ativar o GitHub Actions, confira "Gerenciando as configurações do GitHub Actions para um repositório".

Platform navigation

Neste artigo

Qualquer pessoa com permissões de leitura para um repositório pode testar um site do GitHub Pages localmente.

Pré-requisitos

Antes de usar o Jekyll para testar um site, você deve:

Recomendamos usar o Bundler para instalar e executar o Jekyll. O Bundler gerencia as dependências do gem do Ruby, reduz os erros de compilação do Jekyll e evita erros relacionados ao ambiente. Para instalar o bundler:

  1. Instale o Ruby. Para obter mais informações, confira "Como instalar o Ruby" na documentação do Ruby.
  2. Instale o Bundler. Para obter mais informações, confira "Bundler".

Dica: caso você receba um erro do Ruby ao tentar instalar o Jekyll usando o Bundler, talvez seja necessário usar um gerenciador de pacotes, como o RVM ou o Homebrew, para gerenciar a instalação do Ruby. Para obter mais informações, confira "Solução de problemas" na documentação do Jekyll.

Criar site localmente

  1. Abra TerminalTerminalGit Bash.

  2. Navegue até a fonte de publicação do seu site. Para obter mais informações, confira "Configurar uma fonte de publicação para o site do GitHub Pages".

  3. Execute bundle install.

  4. Execute o site do Jekyll localmente.

    $ bundle exec jekyll serve
> Configuration file: /Users/octocat/my-site/_config.yml
>            Source: /Users/octocat/my-site
>       Destination: /Users/octocat/my-site/_site
> Incremental build: disabled. Enable with --incremental
>      Generating...
>                    done in 0.309 seconds.
> Auto-regeneration: enabled for '/Users/octocat/my-site'
> Configuration file: /Users/octocat/my-site/_config.yml
>    Server address: http://127.0.0.1:4000/
>  Server running... press ctrl-c to stop.

    Observações:

    • Se você tiver instalado o Ruby 3.0 ou posterior (o que poderá acontecer se você tiver instalado a versão padrão via Homebrew), poderá receber um erro nessa etapa. Isso ocorre porque essas versões do Ruby não vêm mais com o webrick instalado.

      Para corrigir o erro, tente executar bundle add webrick e depois executar bundle exec jekyll serve novamente.

    • Se, no arquivo _config.yml, o campo baseurl contém o link do repositório GitHub, você pode usar o seguinte comando ao compilar localmente para ignorar esse valor e servir o site no localhost:4000/:

      bundle exec jekyll serve --baseurl=""

  5. Para visualizar seu site, no navegador da Web, navegue até http://localhost:4000.

Atualizar o gem do GitHub Pages

O Jekyll é um projeto ativo de código aberto que é atualizado com frequência. Se o gem github-pages do computador estiver desatualizado com o gem github-pages do servidor do GitHub Pages, seu site poderá parecer diferente quando criado localmente do que quando publicado no GitHub. Para evitar isso, atualize regularmente o gem github-pages do computador.

  1. Abra TerminalTerminalGit Bash.
  2. Atualize o gem github-pages.
    • Se você instalou o Bundler, execute bundle update github-pages.
    • Se você não tiver o Bundler instalado, execute gem update github-pages.

Leitura adicional