Advertisement
  1. Web Design
  2. Jekyll

Como Criar e Publicar um Tema do Jekyll em Gem

by
Difficulty:IntermediateLength:MediumLanguages:

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