Sobre o GitHub Pages e Jekyll

Neste artigo

• Sobre o Jekyll
• Configurar o Jekyll em seu site do GitHub Pages
• Material inicial
• Temas
• Plugins
• Realce de sintaxe
• Criar site localmente

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 o 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

To set variables and metadata, such as a title and layout, for a page or post on your site, you can add YAML front matter to the top of any Markdown or HTML file. For more information, see "Front Matter" in the Jekyll documentation.

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

You can add a Jekyll theme to your GitHub Pages site to customize the look and feel of your site. Para obter mais informações, consulte "Temas" na documentação do Jekyll.

You can add a theme to your site manually. For more information, see "Supported themes" on the GitHub Pages site and "Adding a theme to your GitHub Pages site using 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.

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. Para mais informações sobre destaque de sintaxe em GitHub Enterprise, 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

Changes to your site are published automatically when the changes are merged into your site's publishing source. If you want to preview your changes first, you can make the changes locally instead of on GitHub Enterprise. Then, test your site locally. Para obter mais informações, consulte "Testar seu site do GitHub Pages localmente com o Jekyll".