Sobre o GitHub Pages e o Jekyll

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 saber mais, 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, confira Temas com suporte no site do GitHub Pages e Como adicionar um tema ao seu 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.

Tip

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 saber mais, 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".