Sobre o GitHub Pages e 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, consulte Jekyll.

O Jekyll não é oficialmente compatível com o Windows. Para obter mais informações, consulte "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, consulte "Sobre GitHub Pages".

Configurar o Jekyll em seu site do GitHub Pages

É possível configurar a maioria das definições do Jekyll, como o tema e os plugins do seu site, editando o arquivo _config.yml. Para obter mais informações, consulte "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 localizadas em uma pasta chamada /node_modules ou /vendor
• começam com _, . ou #
• terminam com ~
• são excluídos pela configuração exclude em seu arquivo de configuração

Se quiser que o Jekyll processe algum desses arquivos, você poderá usar a configuração includes 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, consulte "Front Matter" na documentação do Jekyll.

Você pode adicionar site.github a uma publicação ou página para incluir metadados de referências de repositório ao seu site. Para obter mais informações, consulte "Usar 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, consulte "Temas" na documentação do Jekyll.

Você pode adicionar um tema ao seu site manualmente. Para mais informações, consulte "Temas compatíveisno site de GitHub Pages e "Adicionar um tema ao seu site de 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, consulte a documentação do seu tema e "Substituir padrões do tema" na documentação do Jekyll.

Plugins

Você pode baixar ou criar plugins do Jekyll para ampliar a funcionalidade do Jekyll em seu site. Por exemplo, o plugin jemoji permite usar emoji em estilo do GitHub em qualquer página do seu site da mesma forma que você faria no GitHub. Para obter mais informações, consulte "Plugins" na documentação do Jekyll.

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

• jekyll-coffeescript
• jekyll-default-layout
• jekyll-gist
• jekyll-github-metadata
• jekyll-optional-front-matter
• jekyll-paginate
• jekyll-readme-index
• jekyll-titles-from-headings
• jekyll-relative-links

Você pode habilitar plugins adicionais incluindo a gem do plugin à configuração plugins em seu arquivo _config.yml. Para obter mais informações, consulte "Configuração" na documentação do Jekyll. Para obter uma lista de plugins compatíveis, consulte "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.

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

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 Server. Para mais informações sobre destaque de sintaxe em GitHub Enterprise Server, consulte "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 Pygments. Se você especificar Pygments no arquivo _config.yml, Rouge será usado no lugar. O Jekyll não pode usar qualquer 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, consulte "Sobre erros de criação do Jekyll para sites do GitHub Pages".

Se quiser usar outro realçador, como highlight.js, você deverá desabilitar o realce da sintaxe do Jekyll atualizando o arquivo _config.yml do projeto.

kramdown:
  syntax_highlighter_opts:
    disable : true

Se o seu tema não incluir CSS para realce da sintaxe, você poderá gerar CSS de realce de sintaxe do GitHub e adicioná-lo ao arquivo style.css do projeto.

$ rougify style github > style.css

Criar site localmente

As alterações no seu site serão publicadas automaticamente quando forem mescladas na fonte de publicação do site. Se você desejar pré-visualizar suas alterações primeiro, você poderá fazer as alterações localmente em vez de fazer em GitHub Enterprise Server. Em seguida, teste seu site localmente. Para obter mais informações, consulte "Testar seu site do GitHub Pages localmente com o Jekyll".