Sobre o GitHub Pages e o Jekyll

Jekyll é um gerador de site estático com suporte integrado para 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

Sobre o Jekyll

O Jekyll é um gerador de site estático com suporte integrado para GitHub Pages e um processo de compilação simplificado. O Jekyll usa arquivos Markdown e HTML, além de criar um site estático completo com base na sua escolha de layouts. O Jekyll aceita Markdown e Liquid, uma linguagem de modelagem que carrega conteúdo dinâmico no site. Para obter mais informações, confira Jekyll.

O Jekyll não é oficialmente compatível com o Windows. Para obter mais informações, confira "Jekyll no Windows" na documentação do Jekyll.

É recomendável usar o Jekyll com o GitHub Pages. Se preferir, você pode usar outros geradores de site estáticos ou personalizar seu próprio processo de compilação localmente ou em outro servidor. Para obter mais informações, confira "Sobre o GitHub Pages".

Configurar o Jekyll em seu site do GitHub Pages

É possível definir a maioria das configurações do Jekyll, como o tema e os plugins do seu site, editando o arquivo _config.yml. Para obter mais informações, confira "Configuração" na documentação do Jekyll.

Algumas definições de configuração não podem ser alteradas para sites do GitHub Pages.

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

Por padrão, o Jekyll não cria arquivos nem pastas que:

  • Estão localizados em uma pasta chamada /node_modules ou /vendor
  • Começam com _, . ou #
  • Terminam com ~
  • São excluídos pela configuração exclude no arquivo de configuração

Caso deseje que o Jekyll processe algum desses arquivos, use a configuração include no arquivo de configuração.

Material inicial

Para definir variáveis e metadados, como um título e layout, para uma página ou publicação no seu site, você pode adicionar a página inicial YAML na parte superior de qualquer arquivo Markdown ou HTML. Para obter mais informações, confira "Front Matter" na documentação do Jekyll.

Você pode adicionar site.github a uma postagem ou a uma página para incluir metadados de referências do repositório no seu site. Para obter mais informações, confira "Como usar o site.github" na documentação de metadados do Jekyll.

Temas

É possível adicionar um tema do Jekyll ao site do GitHub Pages para personalizar a aparência do seu site. Para obter mais informações, confira "Temas" na documentação do Jekyll.

Adicione um tema com suporte ao seu site no GitHub. Para obter mais informações, veja “Supported themes” no site do GitHub Pages e “Adicionar um tema ao site do GitHub Pages usando Jekyll”.

Para usar qualquer outro tema do Jekyll de código aberto hospedado no GitHub, adicione o tema manualmente. Para saber mais, confira temas hospedados no GitHub e "Adicionar um tema ao site do GitHub Pages usando Jekyll".

Você pode substituir qualquer um dos padrões do seu tema editando os arquivos do tema. Para obter mais informações, confira a documentação do tema e "Como substituir os padrões do tema" na documentação do Jekyll.

Plug-ins

Você pode baixar ou criar plugins do Jekyll para ampliar a funcionalidade do Jekyll em seu site. Por exemplo, o plug-in jemoji permite usar emojis no estilo do GitHub em qualquer página do seu site da mesma forma que você usaria no GitHub. Para obter mais informações, confira "Plug-ins" na documentação do Jekyll.

O GitHub Pages usa plugins que são habilitados por padrão e não podem ser desabilitados:

Habilite outros plugins adicionando o gem do plug-in à configuração de plugins no arquivo _config.yml. Para obter mais informações, confira "Configuração" na documentação do Jekyll.

Para obter uma lista de plug-ins com suporte, confira "Versões de dependência" no site do GitHub Pages. Para obter informações de uso para um plugin específico, consulte a documentação do plugin.

Dica: você pode garantir que está usando a última versão de todos os plug-ins mantendo o gem do GitHub Pages atualizado. Para saber mais, confira "Testar o site do GitHub Pages localmente com o Jekyll" e "Versões de dependência" no site GitHub Pages.

O GitHub Pages não pode criar sites usando plugins incompatíveis. Se quiser usar plugins incompatíveis, gere seu site localmente e faça push dos arquivos estáticos do site no GitHub Enterprise Cloud.

Realce de sintaxe

Para facilitar a leitura do seu site, trechos de código são destacados nos sites do GitHub Pages da mesma maneira que são destacados no GitHub Enterprise Cloud. Para saber mais sobre realce de sintaxe em GitHub Enterprise Cloud, confira "Criar e realçar blocos de código".

Por padrão, blocos de código no seu site serão destacados pelo Jekyll. O Jekyll usa o realçador Rouge (que é compatível com o Pygments). Se você especificar o Pygments no arquivo _config.yml, o Rouge será usado para fallback. O Jekyll não pode usar nenhum outro realçador de sintaxe e você receberá um aviso de criação de página se especificar outro realçador de sintaxe no arquivo _config.yml. Para obter mais informações, confira "Sobre erros de criação do Jekyll para sites do GitHub Pages".

Caso você deseje usar outro realçador, por exemplo highlight.js, você precisa desabilitar o realce de sintaxe do Jekyll atualizando o arquivo do projeto _config.yml.

kramdown:
  syntax_highlighter_opts:
    disable : true

Se o seu tema não incluir CSS para realce de sintaxe, gere o CSS de realce de sintaxe do GitHub e adicione-o ao arquivo style.css do projeto.

rougify style github > style.css

Criar site localmente

Se você estiver publicando de um branch, as alterações no seu site serão publicadas automaticamente quando forem mescladas na fonte de publicação do seu site. Se você estiver publicando de um fluxo de trabalho personalizado de GitHub Actions, as alterações serão publicadas sempre que seu fluxo de trabalho for disparado (normalmente por um push para o branch padrão). Se você desejar pré-visualizar suas alterações primeiro, você poderá fazer as alterações localmente em vez de fazer em GitHub Enterprise Cloud. Em seguida, teste seu site localmente. Para obter mais informações, confira "Testar o site do GitHub Pages localmente com o Jekyll".