() translation by (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?
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!
Linha de Comando para o Web Design: Introdução
Linha de Comando para o Web Design: Entendendo o Básico
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:
1 |
$ gem install jekyll |
Também precisará do Bundler, que é uma gem para administrar outras gems. Explicarei o porque disso mais tarde. Pode instalá-lo assim:
1 |
$ gem install bundler |
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:
1 |
$ jekyll new-theme awesome-jekyll-theme
|
Será possível ver algo parecido à listagem abaixo:
1 |
awesome-jekyll-theme/ |
2 |
_includes/ |
3 |
_layouts/ |
4 |
default.html |
5 |
page.html |
6 |
post.html |
7 |
_sass/ |
8 |
assets/ |
9 |
Gemfile |
10 |
LICENSE.txt |
11 |
awesome-jekyll-theme.gemspec |
12 |
README.md |
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:
1 |
assets/ |
2 |
styles.scss |
3 |
scripts.js |
4 |
theme-logo.png |
É 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:
1 |
# coding: utf-8
|
2 |
|
3 |
Gem::Specification.new do |spec|
|
4 |
spec.name = "awesome-jekyll-theme" |
5 |
spec.version = "0.0.2" |
6 |
spec.authors = ["David Darnes"] |
7 |
spec.email = ["me@daviddarnes.com"] |
8 |
|
9 |
spec.summary = %q{A short explanation of my awesome gem theme.} |
10 |
spec.description = "A longer explanation of my awesome gem theme that isn’t the same as my summary." |
11 |
spec.homepage = "https://alembic.darn.es" |
12 |
spec.license = "MIT" |
13 |
|
14 |
spec.files = git ls-files -z.split("\x0").select { |f| f.match(%r{^(assets|_layouts|_includes|_sass|LICENSE|README)}i) } |
15 |
|
16 |
spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.0" |
17 |
|
18 |
spec.add_development_dependency "jekyll", "~> 3.3" |
19 |
spec.add_development_dependency "bundler", "~> 1.12" |
20 |
end |
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:
1 |
source "https://rubygems.org" |
2 |
gemspec |
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:
1 |
$ bundle install |
Isso instalará todas as gems do arquivo .gemspec que, nesse exemplo, será apenas jekyll-seo-tag. Agora, podemos executar o tema localmente usando:
1 |
$ bundle exec jekyll serve |
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:
1 |
gem build awesome-jekyll-theme.gemspec |
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:
1 |
gem push awesome-jekyll-theme-0.0.2.gem |
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:
- Documentação oficial do Jekyll sobre criação de temas
- O guia do RubyGems.org sobre criação de gems
- O fórum oficial do Jekyll, com tópicos úteis e a comunidade Jekyll em si.
- Tópico sobre temas em gem no fórum do Jekyll
