Advertisement
  1. Web Design
  2. Jekyll

Como Criar e Publicar um Tema do Jekyll em Gem

Scroll to top
Read Time: 9 mins

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Um recurso notável do novo Jekyll é a possibilidade de criar temas oficias na forma de gems do Ruby. Esses temas podem ser instalados por um usuário do Jekyll para estilizar seus blogs ou sites estáticos facilmente, permitindo-os focar só no conteúdo.

Antes desse recurso, Kezz Bracey escreveu um ótimo tutorial sobre como criar temas para Jekyll. Nesse tutorial, extenderemos a publicação de Kezz, convertendo o modelo em uma gem de tema oficial do Jekyll.

Jekyll na Envato Market

A categoria Jekyll na Themeforest tem alguns temas variando de US$16 a US$29. Por que não submeter o seu próprio, como uma Gem do Ruby?

Jekyll on ThemeforestJekyll on ThemeforestJekyll on Themeforest
Temas para Jekyll no Themefores

Preparação

Antes de começarmos, recomendamos ler o tutorial anterior. Assumiremos que já possui um tema do Jekyll criado usando o método de Kezz ou até criado um site em Jekyll que gostaria de converter em um tema oficial.

Precisaremos usar a linha de comando ao trabalhar com temas do Jekyll, mas, de novo, a Kezz vem ao resgate!

Abra sua ferramenta de linha de comando e tenha certeza de ter instalada a versão mais recente do Jekyll (até o momento do artigo, era a 3.3), usando o comando a seguir:

Também precisará do Bundler, que é uma gem para administrar outras gems. Explicarei o porque disso mais tarde. Pode instalá-lo assim:

Finalmente, precisará criar uma conta no RubyGems.org. Com isso, poderá enviar seu tema para o registro dele e, assim, outros usuários possam baixá-lo e usá-lo.

Começando

Para começarmos, Jekyll tem um comando para criar um novo tema. Em sua ferramenta de linha de comando, ache o diretório que trabalhará e use o comando a seguir para criar os arquivos base do seu tema:

Será possível ver algo parecido à listagem abaixo:

Os diretórios _layouts/_includes/ e _sass/ são os mesmo diretórios que você veria em um projeto Jekyll normal, contendo todos os layouts de suas páginas, parciais e arquivos Sass.

A pasta assets/ é para os arquivos que quiser usar no site. Por exemplo, JavaScript, imagens ou arquivos de estilo. O normal seria os arquivos nas pastas js/, css/ e images/.

awesome-jekyll-theme.gemspec é o arquivo que descreve seu tema. Aqui listaremos o nome, versão, descrição, seu site e uma lista de gems usadas no tema.

O arquivo Gemfile é para o Bundler, que mencionamos antes. Isso liga as gems no arquivo .gemspec com Bundler na linha de comando. Usaremos o Bundler depois para testar o tema.

Por fim, os arquivos README.md e LICENSE.txt são para documentar o tema e prover uma licença apropriada. Talvez já tenha familiaridade com esses arquivos caso já tenha criado projetos no GitHub antes.

Nota: É importante documentar bem seu tema. Dessa forma, aqueles que quiserem usar seu tema poderão fazê-lo facilmente e usar as opções e controles existentes nele.

Convertendo o Tema

Uma vez que projetos Jekyll tem estrutura muito próxima aos temas, podemos copiar a maioria dos arquivos. Provavelmente, quereremos sobrescrever os arquivos de layout existentes, do tema base, com os seus. Assim, todos os arquivos de layout devem ir para _layouts/, as parcias para _includes/ e os arquivos Sass para _sass/, dentro do tema base criado.

Dica: Novato no Sass? Veja esse curso do Adi Purdila, 14 Dias para Aprender Sass.

Precisará colocar seus estilos, JavaScript e imagens dentro do diretório assets/. Isso é importante na criação de temas Jekyll por ser o único diretório livre para usuários do site acessarem. Talvez seu diretório assets fique parecendo com isso:

É preciso atualizar os caminhos dos arquivos no código, refletindo a mudança. Por exemplo, css/styles.scss mudará para assets/styles.scss.

Dica: Garanta que seus caminhos estejam corretos no tema, talvez queira dar uma olhada em relative_url e absolute_url, adicionadas recentemente ao Jekyll.

Os Metadados do Tema

O arquivo .gemspec é projetado para prover informação base sobre seu tema. O tema base do Jekyll vem com esse arquivo mas precisará alterar os valores iniciais com os seus. Eis um exemplo de .gemspec:

Abaixo temos as mudanças feitas no arquivo .gemspec:

name deve ser o nome do tema, combinando com o nome do arquivo .gemspec. version deve ser o número do último lançamento do seu tema. authors pode ser uma lista de pessoas, mas, por hora, apenas temos nós mesmos. email deve ser o mesmo e-mail registrado no RubyGems.org.

Os campos summary e description devem ser explicações curtas e longas sobre seu tema, respectivamente. Pode-se configurar homepage para uma versão demo do tema ou o repositório do GitHub onde o tema fica.

license deve casar com qualquer que seja a licença provida no tema (o arquivo LICENSE.txt). files deve ficar inalterado já que marca os arquivos e diretórios usados na versão final do tema.

A última parte do .gemspec é uma lista de gems que são necessárias para o tema funcionar corretamente. No nosso exemplo, temos apenas uma gem necessária: jekyll-seo-tag. As outras gems listas, jekyll e bundler, são gems de desenvolvimento e necessárias apenas enquanto alguém desenvolve o tema.

É preciso que todas as gems necessárias estão nesse arquivo. Pode-se encontrar uma lista de todos os plugins do Jekyll no site.

Testando o Tema

Agora que temos nossos arquivos do tema e o .gemspec foi preenchido, podemos iniciar os testes. Contudo, precisaremos de algum conteúdo, então copiemos o arquivo _config.yml do antigo tema, assim como alguns arquivos markdown. Um index.md com algum conteúdo deve ser suficiente para um teste inicial, mas talvez queira alguma publicação. Blog é um dos recursos chave do Jekyll, logo, seria bom testá-lo também.

Nota: Garanta que o front matter tem um layout selecionado ou poderá não ver o tema funcionando corretamente localmente.

Lembra que instalamos o Bundler e o Gemfile no diretório raiz do nosso tema? Pois bem, Bundler usa Gemfile para administrar gems em projetos e se abrimo-lo, vermos o seguinte:

Esse arquivo diz ao Bundler para ir ao RubyGems.org e buscar as gems dos seu .gemspec. Sabendo disso, testemos o tema.

Na linha de comando, use o comando abaixo para instalar todas as gems necessárias para o tema:

Isso instalará todas as gems do arquivo .gemspec que, nesse exemplo, será apenas jekyll-seo-tag. Agora, podemos executar o tema localmente usando:

E podemos ver nosso tema no endereço http://localhost:4000. Se ocorrer algum erro, pode ser por esquecermos alguma gem no .gemspec.

Nota: Talvez seja preciso autorizar as gems no arquivo _config.yml, caso não o tenha feito, assim como listadas no .gemspec. Se tiver dificuldades em entender o Jekyll, Guy Routledge criou um ótimo curso no Tuts+, Construindo Sites Estáticos com Jekyll.

Refinando e Adicionando Customização

Agora, é bom passar refinar o tema para garantir que ele funcione com varios formatos e tamanhos de conteúdo. Também é bom consideramos algumas opções de customização, seja global, no _config.yml ou em páginas separadas, no front matter.

O usuário tem a abilidade de sobrescrever qualquer arquivo no tema com seu próprio arquivo no site Jekyll deles. Por exemplo, se tivermos _includes/header.html no tema, o usuário pode sobrescrevê-lo com sua própria versão do _includes/header.html. Talvez seja bom tornar o tema flexível o suficiente, permitindo o usuário sobrescrever os arquivos com os seus próprios.

Documentação

Se adicionarmos customização ao tema, precisamos documentá-la. Isso é muito importante. Se ela é fraca, as pessas não quererão usar o tema.

Eis alguns pontos que são esperados na documentação de um tema:

  • Uma boa descrição do tema e seus usos
  • Lista de recursos
  • Instruções de istalação claras
  • Conteúdo demo mostrando como usar o tema
  • Como as opções de configuração funcionam
  • Como a página de opções funciona
  • Quaisquer códigos ou inclusões que podem ser usados
  • Referências a quaisquer projetos open source usados para criar o tema

Tudo isso pode ser listdo no README.md, criado quando usamos o gerador de temas do Jekyll. Ao ser enviado para RubyGems.org, o arquivo readme será processado e apresentado na página da gem para as pessoas lerem.

Junto da documentação, é recomendar algum conteúdo demo para agilizar o uso do seu tema. Arquivos _config.yml, index.md e de publicação, similares aos usados para testar o tema, junto do Gemfile, serão suficientes. Embora apenas requira que o usuário adicione a gem ao Gemfile deles, seria bem útil prover um exemplo de configuração que podem baixar e usar.

É preciso prover uma captura de tela, como dito na documentação oficial do Jekyll, com o nome screenshot.png. Não apenas permitirá que as pessoas vejam como o tema parece, mas também proverá consistência entre todos os temas Jekyll, de modo que poderão ser apresentados em uma galeria ou interface administrativa no futuro.

Publicando o Tema

Quando feliz com o tema, tendo-o testado e documentado, é preciso enviar para o RubyGems.org para os outros baixarem.

Ache o seu tema na linha de comando e use o comando a seguir:

Tenha certeza de digitar o nome correto da sua .gemspec do seu tema com o comando acima. Isso criará um arquivo chamado awesome-jekyll-theme-0.0.2.gem, que é uma gem de tema Jekyll oficial. Agora, basta enviar para o RubyGems.org. Usemos o comando abaixo na linhda de comando:

Se for a primeira vez enviando uma gem para o RubyGems.org, será pedido pra logar. Após isso, a gem estará no registro e seu tema estará publicado.

Dica: Na maioria das ferramentas de linha de comando, se digitar as primeiras letrar de um arquivo e pressionr Tab, o nome deverá ser autocompletado, desde que não haja nenhum outro arquivo de mesmo nome no diretório.

Feito isso, é preciso mais testes e seguir as próprias instruções (do README.md) ao instalar e usar o tema. As instruções deveriam ser bem parecias às que aparecem no site oficial do Jekyll.

Leitural Adicional

Além de seguir o tutorial, talvez queira checar esses outros recurso relacionados a criação de gem de temas para Jekyll:

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Web Design tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.