Solucionar problemas de erros de criação do Jekyll para sites do GitHub Pages

Você pode usar mensagens de erro de criação do Jekyll para solucionar problemas com seu site do GitHub Pages.

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".

Neste artigo

Solucionar problemas de erros de criação

Se o Jekyll encontrar um erro ao criar seu site do GitHub Pages localmente ou no GitHub, você poderá usar mensagens de erro para solucionar problemas. Para obter mais informações sobre mensagens de erro e como visualizá-las, confira "Sobre erros de criação do Jekyll para sites do GitHub Pages".

Se você recebeu uma mensagem de erro genérica, verifique os problemas comuns.

  • Você está usando plugins incompatíveis. Para mais informações, confira "Sobre o GitHub Pages e o Jekyll".
  • Seu repositório excedeu os limites de tamanho. Para obter mais informações, confira "Sobre arquivos grandes no GitHub"
  • Você alterou a configuração de source em seu arquivo _config.yml. Se você publicar seu site de um branch, GitHub Pages substituirá essa configuração durante o processo de build.
  • Um nome de arquivo em seus arquivos publicados contém dois-pontos (:), o que não é permitido.

Se você recebeu uma mensagem de erro específica, revise abaixo as informações de solução de problemas relativas à mensagem de erro.

Após corrigir os erros, acione outra compilação transmitindo as alterações para a ramificação de origem do site (se você estiver publicando a partir de uma ramificação) ou acionando seu fluxo de trabalho personalizado GitHub Actions (se você estiver publicando com GitHub Actions).

Erro no arquivo de configuração

Este erro indica que ocorreu falha na criação do seu site porque o arquivo _config.yml contém erros de sintaxe.

Para solucionar problemas, verifique se o arquivo _config.yml segue estas regras:

  • Use espaços em vez de abas.
  • Inclua um espaço após : para cada par chave/valor, como timezone: Africa/Nairobi.
  • Use apenas caracteres com codificação UTF-8.
  • Cite quaisquer caracteres especiais, tais como :, como title: "my awesome site: an adventure in parse errors".
  • Para valores de várias linhas, use | para criar novas linhas e > ignorá-las.

Para identificar os erros, copie e cole o conteúdo do arquivo YAML em um linter YAML, como o YAML Validator.

Note: If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see "Documentação do GitHub Actions."

Esta é uma data/hora inválida

Este erro indica que uma das páginas do seu site inclui uma data/hora inválida.

Para solucionar problemas, pesquise o arquivo na mensagem de erro e os layouts do arquivo para as exigências de qualquer filtro de data do Liquid. Verifique se alguma variável passada em filtros de data do Liquid tem valores em todos os casos e nunca passa nil ou "". Para obter mais informações, confira "Filtros Liquid" na documentação Liquid.

O arquivo não existe no diretório includes

Este erro indica que o código faz referência a um arquivo que não existe no diretório _includes.

Para solucionar problemas, pesquise o arquivo na mensagem de erro em busca de include para ver em que locais você referenciou outros arquivos, como {% include example_header.html %}. Se algum dos arquivos a que você fez referência não está no diretório _includes, copie ou mova os arquivos para o diretório _includes.

Arquivo codificado por UTF-8 incorretamente

Este erro indica que você usou caracteres não latinos, como 日本語, sem avisar ao computador que esperava esses símbolos.

Para solucionar problemas, force a codificação UTF-8 adicionando a seguinte linha ao arquivo _config.ymll:

encoding: UTF-8

Linguagem inválida do realçador

Esse erro indica que você especificou qualquer realce de sintaxe diferente de Rouge ou Pygments no arquivo de configuração.

Para solucionar problemas, atualize seu arquivo _config.yml para especificar Rouge ou Pygments. Para obter mais informações, confira "Sobre o GitHub Pages e o Jekyll".

Data de postagem inválida

Este erro indica que uma postagem no seu site contém uma data inválida no nome de arquivo ou na página inicial YAML.

Para solucionar problemas, verifique se todas as datas estão no formato YYYY-MM-DD HH:MM:SS para UTC e se são datas reais do calendário. Para especificar um fuso horário com um intervalo de tempo UTC, use o formato YYYY-MM-DD HH:MM:SS +/-TTTT (ano-mês-dia horas:minutos:segundos +/-TTTT), como 2014-04-18 11:30:00 +0800.

Se você especificar um formato de data no arquivo _config.yml, verifique se o formato está correto.

Sass ou SCSS inválido

Este erro indica que seu repositório contém um arquivo Sass ou SCSS com conteúdo inválido.

Para solucionar problemas, revise o número de linha incluído na mensagem de erro referente a Sass ou SCSS inválido. Para ajudar a prevenir erros no futuro, instale um linter Sass ou SCSS para seu editor de texto favorito.

Submódulo inválido

Este erro indica que seu repositório inclui um submódulo que não foi inicializado corretamente.

Para solucionar problemas, primeiro decida se você realmente deseja usar um submódulo, que é um projeto do Git dentro de um projeto Git; às vezes, submódulos são criados acidentalmente.

Se você não quiser usar um submódulo, remova-o substituindo PATH-TO-SUBMODULE pelo caminho para o submódulo:

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Caso queira utilizar o submódulo, lembre-se de usar https:// quando fizer referência ao submódulo (não http://) e de que o submódulo está em um repositório público.

YAML inválido no arquivo de dados

Este erro indica que um ou mais arquivos na pasta _data contém YAML inválido.

Para solucionar problemas, verifique se os arquivos YAML na pasta _data seguem estas regras:

  • Use espaços em vez de abas.
  • Inclua um espaço após : para cada par chave/valor, como timezone: Africa/Nairobi.
  • Use apenas caracteres com codificação UTF-8.
  • Cite quaisquer caracteres especiais, tais como :, como title: "my awesome site: an adventure in parse errors".
  • Para valores de várias linhas, use | para criar novas linhas e > ignorá-las.

Para identificar os erros, copie e cole o conteúdo do arquivo YAML em um linter YAML, como o YAML Validator.

Para obter mais informações sobre arquivos de dados Jekyll, confira "Arquivos de Dados" na documentação do Jekyll.

Erros de markdown

Este erro indica que seu repositório contém erros de markdown.

Para solucionar problemas, verifique se você está usando um processador markdown compatível. Para obter mais informações, confira "Definir um processador markdown para seu site do GitHub Pages usando o Jekyll".

Em seguida, verifique se o arquivo na mensagem de erro usa uma sintaxe markdown válida. Para obter mais informações, confira "Markdown: Sintaxe" do Daring Fireball.

Pasta docs ausente

Este erro indica que você escolheu a pasta docs em um branch como a sua fonte de publicação, mas não há nenhuma pasta de docs na raiz do seu repositório naquele branch.

Para solucionar esse problema, se a sua pasta docs foi movida acidentalmente, tente mover a pasta docs de volta para a raiz de seu repositório na ramificação que você escolheu para sua fonte de publicação. Se a pasta docs tiver sido excluída acidentalmente, você poderá:

  • Use o Git para reverter ou desfazer a exclusão. Para obter mais informações, confira "git-revert" na documentação do Git.
  • Crie uma nova pasta de docs na raiz do repositório no branch que você escolheu para a sua fonte de publicação e adicione os arquivos de origem do site à pasta. Para obter mais informações, confira "Criar arquivos".
  • Altere a fonte de publicação. Para obter mais informações, confira "Configurar uma fonte de publicação para o site do GitHub Pages".

Submódulo ausente

Este erro indica que seu repositório inclui um submódulo que não existe ou não foi inicializado corretamente.

Para solucionar problemas, primeiro decida se você realmente deseja usar um submódulo, que é um projeto do Git dentro de um projeto Git; às vezes, submódulos são criados acidentalmente.

Se você não quiser usar um submódulo, remova-o substituindo PATH-TO-SUBMODULE pelo caminho para o submódulo:

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Se você quiser usar um submódulo, inicialize-o. Para obter mais informações, confira "Ferramentas do Git – Submódulos" no livro Pro Git.

Este erro indica que você tem permalinks relativos aos quais GitHub Pages não dá suporte em seu arquivo _config.yml.

Permalinks são URLs permanentes que fazem referência a uma determinada página no seu site. Os permalinks absolutos iniciam com a raiz do site, enquanto os permalinks relativos iniciam com a pasta que contém a página referenciada. O GitHub Pages e o Jekyll não são mais compatíveis com permalinks relativos. Para obter mais informações sobre permalinks, confira "Permalinks" na documentação do Jekyll.

Para solucionar problemas, remova a linha relative_permalinks do arquivo _config.yml e reformate todos os permalinks relativos em seu site com permalinks absolutos. Para obter mais informações, confira "Editando arquivos".

Erro de sintaxe no loop 'for'

Este erro indica que o código inclui sintaxe inválida em uma declaração de loop for do Liquid.

Para solucionar problemas, verifique se todos os loops for no arquivo da mensagem de erro têm sintaxe adequada. Para obter mais informações sobre a sintaxe adequada para loops for, confira "Tags de iteração" na documentação do Liquid.

Tag fechada incorretamente

Esta mensagem de erro indica que o código inclui uma tag lógica que foi fechada incorretamente. Por exemplo, {% capture example_variable %} deve ser fechado por {% endcapture %}.

Para solucionar problemas, verifique se todas as tags lógicas no arquivo da mensagem de erro estão fechadas corretamente. Para obter mais informações, confira "Tags Liquid" na documentação Liquid.

Tag terminada incorretamente

Este erro indica que o código inclui uma tag de saída que não foi terminada corretamente. Por exemplo, {{ page.title } em vez de {{ page.title }}.

Para solucionar problemas, verifique se todas as tags de saída no arquivo da mensagem de erro estão terminadas com }}. Para obter mais informações, confira "Objetos Liquid" na documentação Liquid.

Erro de tag desconhecida

Este erro indica que o código contém uma tag do Liquid não reconhecida.

Para solucionar problemas, verifique se todas as tags do Liquid no arquivo da mensagem de erro correspondem a variáveis padrão do Jekyll e se não há erros de digitação nos nomes das tags. Para obter uma lista de variáveis padrão, confira "Variáveis" na documentação do Jekyll.

Plugins incompatíveis são uma fonte comum de tags não reconhecidas. Se você usar um plugin incompatível ao gerar seu site localmente e fazer push dos arquivos estáticos para o GitHub, verifique se o plugin não está inserindo tags que não estão nas variáveis padrão do Jekyll. Para obter uma lista de plug-ins com suporte, confira "Sobre o GitHub Pages e o Jekyll".