Criando blogs com Jekyll no Windows

Jekyll

Jekyll é um programa escrito em Ruby que permite a criação dinâmica de websites e blogs utilizando apenas html, css e javascript. Entenda o que é o Jekyll neste artigo: “O que é e para que serve o Jekyll”, no qual explicamos detalhadamente como ele funciona.

Vantagens de utilizar o Jekyll

Não há necessidade da criação de uma base de dados, o que o torna absolutamente seguro. Ele dinamiza o código html, assim como as extensões baseadas em liguagem de servidor (como php, por exemplo), mas sem a necessidade da leitura do próprio servidor.

O mais interessante é que o Jekyll é suportado pelo GitHub Pages, permitindo assim que websites e blogs escritos em Jekyll sejam hospedados gratuitamente no GitHub.

Ao criar um novo website com o comando jekyll new nome-do-blog, uma pasta nome-do-blog é automaticamente formulada pelo Jekyll, trazendo a estrutura básica para desenvolvimento do site, incluindo a programação da formulação de blogs. Ou seja, não é necessário que você escreva todo o escopo do projeto, o próprio comando traz a estrutura pronta para você desenvolvê-la.

O Jekyll foi primeiramente desenvolvido para computadores MAC, em que a instalação e utilização é simples e direta. As últimas versões já estão disponíveis para Windows, mas requerem um pouco mais de esforço para deixar tudo funcionando como deve.

Devido à falta de informações e tutoriais nesta área específica, resolvi deixar minha contribuição para quem tem se batido com o Jekyll para Windows, e contar para vocês como consegui fazê-lo funcionar.


Criando seu projeto com o Jekyll no Windows (Win 7)

Programas e gems necessários para a instalação (veja abaixo as notas referentes às marcações (1), (2), (3), (4), e (*)):

Recomendados: - Rails - instalador

Updates: Upgrade de Jekyll 2 para Jekyll 3 - não mais recomendados para Jekyll 3.x:

- Python / Pip / Redcarpet / Easy-Install / Pygments ou (4)

Outros: - Windows Directory Monitor - para usuários do Windows - RDiscount - dependência para algumas gems

* Fundamental:

A instalação destes programas é fundamental para um funcionamento perfeito do Jekyll.

(1) Atenção:

Ruby: no próprio site do Ruby, existe a informação de que a versão Ruby para winx64 ainda está em fase inicial e pode não funcionar perfeitamente. Por isso, apesar de ter winx64, preferi optar pela versão para winx32.

(2) Jekyll e GitHub

Git e GitHub Pages: gems necessárias somente para quem pretende hospedar o Jekyll no GitHub Pages.

(3) Sass

O Sass é uma ferramenta fantástica de web design. Não é obrigatória para rodar o Jekyll, mas altamente recomendada. Em breve escreveremos um artigo sobre o Sass e adicionaremos o link aqui.

(4) Markdown / Highlighter

Updates: Upgrade de Jekyll 2 para Jekyll 3

A versão 2 do Jekyll possuía como padrão:

markdown: redcarpet
highlighter: pygments

Já a nova versão Jekyll 3.x possui como padrão:

markdown: kramdown
highlighter: rouge

Portanto, prefira a segunda opção. Desta forma, você evitará a instalação do Python, do Redcarpets, do Pygments e todas suas dependências.

Você precisará instalar as gems necessárias para que consiga utilizar os arquivos em markdown. Não sabe exatamente qual vai usar? Instale todas... O Python é um programa com instalador. Todos os demais são "gems".

Passo-a-passo para a instalação

O passo-a-passo para a instalação dos programas e gems mencionados acima via de regra é longo e pode gerar erros. Por esta razão, recomendo que siga este camarada Yi Zeng, pois o tutorial dele inclui os possíveis erros que podem ocorrer e informa como resolvê-los. Em breve farei a tradução do tutorial dele em um novo artigo deste blog e incluirei o link aqui. Caso você não seja um programador e consiga instalar tudo rapidamente e sem gerar erros, parabéns, você é um vencedor! :smiley:

UPDATE - Jekyll 2 para Jekyll 3: O processo de instalação do Jekyll melhorou significativamente depois da alteração de markdown e highlighter de redcarpet para kramdown e de pygments para rouge, respectivamente. Esta alteração nos padrões reduziu significativamente o número de dependências das gems instaladas e a ausência do Python, um programa voltado a programadores, mas não utilizado por todos os desenvolvedores e designers web.


Criando seu primeiro Blog com Jekyll

Agora que você já conseguiu instalar o Jekyll, vamos criar seu primeiro site.

Abra seu prompt de comando, vá até o diretório onde quer criar seu novo projeto e digite:

jekyll new meuprojeto
# cria uma nova pasta com o nome do seu projeto.
cd meuprojeto
# entra na pasta do seu projeto.
jekyll serve --watch # veja abaixo

Com o comando serve, o Jekyll compilará os arquivos para formar sua estrutura em html e abrirá um servidor local que permite que você veja o site no seu navegador de internet.

Com o comando --watch, o Jekyll acomanhará as mudanças que você fará nos arquivos e repassá para o servidor local o arquivo html compilado. Basta atualizar a página do seu navegador para acompanhar suas alterações.

Se der tudo certo até aqui, você verá uma notificação no seu prompt informando que o Jekyll está rodando neste endereço: server address: http://127.0.0.1:4000. A parte à esqueda da pontuação : corresponde ao seu ip local ou localhost. A parte da direita te informa qual é a porta que o localhost está usando. Para ver seu novo site, vá até seu navagedor e digite localhost:4000 ou o endereço informado pelo prompt de comando, caso seja diferente deste. Ao fazer uma mudança no seu arquivo, você terá que atualizar a página no navegador (F5) para vê-la.

Parando a compilação

Se por algum motivo você quiser parar a compilação do Jekyll, vá ao prompt de comando e aperte Ctrl C no seu teclado. Se quiser alterar o arquivo _config.yml, sobre o qual falaremos logo abaixo, você terá que parar o Jekyll e reiniciá-lo, caso contrário as suas configurações não serão atualizadas. Para reiniciá-lo rapidamente, aperte a seta para cima :arrow_up: do seu teclado que aparecerá seus últimos comandos. Encontre o jekyll serve --watch e aperte enter para reiniciar.

Executando o Jekyll sem erros

A forma mais garantida de usar o Jekyll localmente no seu PC (ou Mac) sem gerar erros é fazendo a instalação e a construção do site com o bundler:

  1. Adicione à raiz do seu projeto um arquivo chamado Gemfile (sem nenhuma extensão).
  2. Neste arquivo, adicione um dos dois blocos abaixo:

    a) caso você não pretenda hospedar seu site no GitHub Pages, adicione ao Gemfile:

     source 'https://rubygems.org'
     gem 'jekyll'
     gem 'kramdown'
     gem 'rouge'
    

    b) caso você pretenda hospedar seu site no GitHub Pages, adicione:

     source 'https://rubygems.org'
     gem 'github-pages'
    

    c) Salve o Gemfile.

  3. Abra o seu terminal na pasta do seu projeto e execute o comando bundle install. O Bundler criará um arquivo chamado Gemfile.lock na raíz do seu projeto. Deixe-o lá.
  4. Execute o Jekyll com o comando bundle exec jekyll serve

Desta forma, via bundler, você estará garantindo que as gems necessárias para construir seu site localmente estão instaladas, assim como todas as suas dependências.

Nota: há outras gems que poderão ser inseridas conforme sua necessidade.


Hospedando gratuitamente com o GitHub Pages

Agora que temos um projeto, e partido do pressuposto que você queira hospedá-lo no GitHub Pages, temos que fazer com que o Jekyll “converse” com o GitHub. Partimos do princípio que você já tenha um repositório pronto para receber seu blog. Para fazer o setup do GitHub Pages, veja o artigo Como publicar seu website no GitHub. Siga-nos no Twitter para ver nossos artigos em primeira mão!

Configuração do _config.yml

Na pasta raiz do seu projeto, encontre o arquivo de configuração _config.yml. Este é o arquivo chave do seu projeto. Nele vão todas as configurações do website, por exemplo: título, autor, email do autor, facebook do autor e todas as outras variáveis que você aprenderá a definir conforme for lendo sobre o assunto.

Para publicar no GitHub Pages, você precisa definir algumas variáveis importantíssimas neste arquivo, como markdown, highlighter e baseurl. Para efeitos de GitHub, o que é fundamental é que você avise ao git onde fica sua “pasta” que hospedará seu site (baseurl). Portanto, informe o seguinte:

Caso comum a todos os websites hospedados no GitHub:

highlighter: rouge
markdown: kramdown
kramdown:
  input: GFM

Caso 1: Website de usuário ou organização:

baseurl: http://usuario.github.io

Caso 2: Website de projetos

baseurl: http://usuario.github.io/seurepositorio

O nome desta “pasta” deverá ser o mesmo nome do seu repositório, conforme documentado nas instruções do Jekyll para baseurl.

Caso seja um website de projeto, isso significa que seu site ou blog morará dentro do branch gh-pages, dentro do seu repositório seuprojeto e que o index será acessado via http://usuario.github.io/seurepositorio. Caso seja um website de usuário/organização, o repositório deverá ser nomeado usuario.github.io e o seu blog morará no branch master e sua home page (index.html) será acessada via http://usuario.github.io. Você poderá ainda redirecionar seu website para um domínio próprio, como suaempresa.com.br.

Caso você utilize o Jekyll no seu próprio domínio, o baseurl deverá estar de acordo com sua pasta raiz:

baseurl: http://www.seudominio.com

Note que há apenas um espaço entre os dois pontos : e a url. Mantenha desta forma. Bagunçar com os espaços nos seus arquivos .yml pode gerar erros na compilação que você ficará louco até encontrar. Portanto, recomendo que não deixe de respeitar os espaços e a pontuação nos seus arquivos Yaml!

Gerando o Gemfile

Segundo as instruções do GitHub, será necessário gerar um “Gemfile” no seu repositório. Siga os passos descritos anteriormente para gerar seu Gemfile para o GitHub Pages.

Lembre-se: caso necessário, inclua outras gems ao seu Gemfile.

Agora você poderá executar o seguinte comando: bundle exec jekyll serve --safe --watch --baseurl "". Isso permitirá que você rode o site no seu localhost novamente, mas sem alterar a definição do baseurl que tínhamos feito anteriormente. A flag --safe é necessária para que você monte seu website localmente exatamente como o GitHub montará. UPDATE: O novo Jekyll 3.x/GitHub Pages possui um BUG no modo seguro. Portanto, execute sem a flag --safe por enquanto, até que o problema seja resolvido: bundle exec jekyll serve --watch --baseurl "".

Se aparecer alguma mensagem de erro, você poderá fazer o update de todas as gems:

gem update # caso não use o bundler - todas as "gems" instaladas serão atualizadas
bundle update # caso use o bundler - todas as "gems" instaladas serão atualizadas
bundle update github-pages # o bundler fará somente o update da gem "github-pages"
gem update github-pages # fará somente o update da gem "github-pages" sem o bundler

Caso haja algum erro ao montar o site, em qualquer momento do seu desenvolvimento, você poderá executar o comando jekyll --trace para mais informações sobre o erro.

Depois de fazer todos os updates, insira novamente o comando bundle exec jekyll serve --watch --baseurl "". Deve funcionar. Caso não funcione, recomendo que volte ao artigo do Yi Zeng para tentar encontrar o erro e corrigi-lo.

Pronto! Seu website deverá estar pronto para que você insira seu conteúdo! :clap: :clap:

Posts

Este artigo já está muito longo, por isso não será detalhado aqui como funciona a estrutura de pastas do projeto. Apenas para oferecer uma pequena introdução, fique atento ao seguinte: a primeira parte de todos os arquivos traz o cabeçalho de configuração do arquivo (originalmente chamada Yaml frontmatter). Esta parte fica sempre no topo, separada do corpo pelos três traços, conforme abaixo:

---
Configurações do post
---

Texto post

No cabeçalho de configuração, você poderá listar tudo que faz parte do post, como: layout, título, descrição, autor, categorias, tags, e tudo que você desejar inserir como padrão.

Para exemplificar, veja abaixo como ficou parte do cabeçalho deste artigo:

---
layout: post
title: Criando blogs com Jekyll no Windows
categories: [Jekyll, Github, Blog, Tutoriais]
tags: [jekyll, git, blog]
description: Como criar blogs com Jekyll no Windows e publicar com o GitHub Pages.
author: Marcia Ramos
---

# **Jekyll**

Jekyll é um programa.....

Estas informações poderão ser recuperadas por todo o site, utilizando tags, objetos e filtros da Liquid Templating Language. Por exemplo, para recuperar o título da página, você poderá utilizar o seguinte objeto:

{{ post.title }} 
# ou
{{ page.title }} 

Estes são apenas exemplos simples. Aprofundaremos os detalhes da escrita em Liquid futuramente, em outros artigos.

Os únicos arquivos que não trarão o cabeçalho se configuração serão os arquivos da pasta _includes. Estes arquivos terão seus conteúdos inseridos dinamicamente através da chamada {{ content }} ou {% include %}. Este tipo de objeto faz parte da estrutura Liquid, que deixaremos para discutir em outros artigos. Para ter um panorama introdutório a este assunto, veja nosso artigo “O que é Jekyll - e para que ele serve”.

Estilizando seu projeto

O projeto padrão do Jekyll (obtido com o comando jekyll new meuprojeto explicado acima) já traz um design interessante. Muitas pessoas não perdem muito tempo estilizando suas páginas, usam o próprio projeto padrão e se aprofundam apenas em seus conteúdos. De qualquer forma, para saber o que é o que, você pode usar o Inspecionar Elemento do seu navegador para interagir com o css e personalizá-lo. Se você não está familiarizado com esta ferramenta, poderá ver este artigo, no qual o autor descreve detalhadamente como utilizá-la. Nesse artigo, o rapaz explica como o “Inpecionar elemento” funciona no Google Chrome, mas no Mozilla Firefox você poderá acessá-la da mesma forma. Há ainda diversos temas gratuitos disponíveis no site Jekyll Themes.

Markdown

Markdown: para ter acesso a uma lista prática de markdowns do Jekyll / GitHub, veja o nosso artigo Jekyll e GitHub Markdown.


+ Mais

Fontes de informação

Para quem entende Inglês, sugiro que siga os tutoriais em vídeo da série Jekyll do Thomas Bradley. Ficará mais fácil compreender como utilizar a estrutura de pastas, as ferramentas e os arquivos em markdown .md do Jekyll.

Recomendo também a leitura do artigo (em Inglês) The joy and pain of using Jekyll, que explica melhor quais são as maiores vantagens e desvantagens de usar o Jekyll.

Há uma outra fonte de prós e contras do Jekyll com o Travis Nielson, em que ele argumenta com seu amigo Jon, ambos designers. O título do vídeo é “Jon doesn’t like Jekyll”.

Você poderá acessar a documentação do Jekyll no Jekyll docs. Se você precisar reportar bugs e novas implementações, poderá fazê-lo no Jekyll’s GitHub repo. Se você tiver dúvidas, eles recomendam que os procure no Jekyll Talk.

Ficaremos muito felizes se puder deixar seu comentário com sugestões e dicas que ajudem a comunidade web!

Atualização (upgrade) do Jekyll 2.x para 3.x

Tivemos que alterar algumas coisas neste artigo para que sigamos compatíveis com a nova versão do Jekyll, que está inclusive sendo utilizada pelo GitHub Pages desde 1º de fevereiro de 2016.

Algumas alterações foram significativas, mas nosso Blog sobreviveu intacto, portanto, considere-se encorajado a alterar seu projeto também. :smiley:

A documentação oficial completa fazendo referência a todas as alterações necessárias para adequar seu projeto ao Jekyll v3.x poderá ser encontrada na página destinada a esta orientação no site oficial do Jekyll: Upgrading from 2.x to 3.x.

A lista de gems utilizadas oficialmente pelo GitHub Pages pode ser encontrada aqui.

Prós & Contras

Infelizmente, para quem está acostumado apenas com a liguagem html/css sem markdown/liquid, o Jekyll pode exigir um certo tempo para aprendizagem, mas todo desenvolvedor web poderá entender rapidamente e aprender a curtir! E, de fato, depois que aprendemos, não apenas passa a ser uma ferramenta de desenvolvimento web excelente como fácil de usar.

Há desenvolvedores que utilizam outros geradores de sites estáticos (Static Site Generators - SSGs), em razão das limitações impostas pelo Jekyll. Neste link, você poderá encontrar uma lista de todos os SSGs que estão rolando por aí. De longe, o Jekyll é o mais utilizado.

Para quem precisa de websites mais elaborados com páginas de login, com CMS, com formulários de cadastro, ou mesmo sites que precisem de atualizações constantes, não costuma-se recomendar nem o Jekyll e nem o GitHub Pages. Eles não têm este propósito e nem permitem estas funcionalidades. Ou melhor, há usuários avançados que fazem verdadeiros milagres com o Jekyll, mas se você ainda é um iniciante em Jekyll, tente primeiro entender todas as funções básicas para depois explorar as avançadas.

De qualquer forma, dependendo da complexidade que você queira atingir, não é possível fugir da programação baseada em linguagem de servidor, como o php faz muito bem. E neste caso, você não poderia utilizar o GitHub Pages, que não suporta php.


Artigos Relacionados

Último update deste artigo: 30/03/2016 às 21:24h.