Após passar certo sufoco para construir e configurar este site com Jekyll e GitHub Pages, aqui está um passo-a-passo de como você pode fazer o seu. Sabe como é, eu sou de humanas. Se eu consegui, você também consegue.

O Jekyll é um gerador super-simplificado de sites estáticos. É grátis, código aberto, e uma ótima plataforma para blogs. Além disso, é a engrenagem por trás do GitHub Pages, o que significa que você tem hospedagem gratuita e integração facilitada com sua máquina através do Git (que é maravilhoso).

Todo o sistema funciona com base em arquivos de texto simples, o que fará você se sentir blogging like a hacker (olha a hype!). Aí está um primeiro obstáculo, você não terá uma interface gráfica mastigadinha como um tumblr, blogger ou worpress, mas contará com ótimos guias e tutoriais para ajudar no processo e terá controle completo sobre seu site ou blog.

Outros requisitos são saber se virar no inglês, já que a maioria dos usuários escrevem nesta língua e ter paciência para procurar informações no google e na documentação do software.

O Jekyll roda nativamente no Linux, Unix, e no Mac OS X. Diz que até funciona no Windows, mas saiba que vai ser meio na gambiarra.

Todo o passo-a-passo descrito nesta postagem foi feito no Debian Jessie, mas a maior parte é comum a todas as distribuições. Durante o guia, eu suponho que você não trema de medo do terminal, saiba rodar comandos como root e que convém um apt-get update antes de instalar qualquer coisa.

Além disso, nenhum conhecimento prévio é necessário, nem qualquer experiência com construção de websites. Vamos lá.

Escolha um tema

Apesar de você ter a opção de começar um site do zero, nós vamos ser mais espertos do que isso e começar escolhendo um tema do jekyll.

Vá, gaste um tempo e escolha um que lhe agrade. Tem para todos os gostos, desde mais simples e minimalistas até alguns bem completos, bacanosos, e até meio extravagantes.

Da minha parte, comecei com o Long Haul, criado por Brian Maier. O tema é simples, bem instrumentalizado, e tem uma documentação razoável, mas acabei modificando muita coisa. Você também pode usar minha própria versão do tema, a.k.a. este site que você acessa agora, como ponto de partida para o seu, mas recomendo começar com um tema mesmo, pela organização, limpeza e tals.

Meu GitHub, minha vida

Uma vez escolhido um tema, é hora de começar com o GitHub:

1. Cadastre-se no GitHub.
2. Faça uma fork do repositório do tema que você escolheu.

   

3. Pronto, você já tem uma cópia completa (uma fork) do tema na sua conta.
4. Nas configurações, mude o nome do seu repositório para seu-nome-de-usuario.github.io. Esta é a dica para que o GitHub Pages publique seu site.

   

Parabéns, você provavelmente já está online em http://seu-nome-de-usuario.github.io Talvez agora você queira trabalhar no formato e conteúdo antes de divulgar o endereço por aí. Vamos a isso.

Trabalhando localmente com o Git e Jekyll

Para criar conteúdo e testar o site antes de deixá-lo brilhar na vida, nós precisamos do Jekyll para montar o site localmente e do Git para publicar as alterações no GitHub.

Você vai precisar também de um editor de texto simples. Eu recomendo fortemente o Sublime Text, que faz super juz ao nome, mas você pode usar qualquer um. O gedit, pré-instalado no Jessie, dá conta do recado.

1. Instale o Git

apt-get install git

2. Instale o Jekyll

Modo fácil

Depois de gastar horas pesquisando e instalando todos os requisitos do Jekyll, descobri que é muito fácil instalá-lo no Debian Jessie. Tão fácil como:

apt-get install jekyll

Modo menos fácil

Mesmo que você seja desafortunado e sua distribuição não tenha esse pacote no repositório, ainda é bastante simples. Segue o passo-a-passo:

Instale as dependências Ruby:

apt-get install ruby
apt-get install ruby2.1-dev #=> ou a versão mais atual disponível

Agora as dependências NodeJS:

apt-get install curl
curl -sL https://deb.nodesource.com/setup | bash -
apt-get install nodejs
apt-get install build-essential

E, finalmente, o Jekyll:

gem install jekyll --user-install

3. Clone seu repositório

Clonar um repositório significa fazer uma cópia em sua máquina. No terminal, navegue para onde deseja fazer o download (por exemplo, /home/Site ) e rode o comando abaixo, substituindo “endereço-do-repositório” pelo endereço real.

git clone endereço-do-repositório

4. Crie conteúdo

      seu-nome-de-usuario.github.io
     ├──  _config.yml
     ├──  index.html
     ├──  _includes
     │   ├──  footer.html
     │   └──  header.html
     ├──  _layouts
     │   ├──  default.html
     │   └──  post.html
     ├──  _posts
     │   ├──  2011-10-25-coxinha-de-jaca.md
     │   └──  2011-04-26-hello-world.md
     └──  _site

A seguir, vai uma apresentação rápida de cada um dos itens. Saiba mais lendo a documentação completa do Jekyll.

_config.yml

• Configurações gerais do site, como título e descrição, vão aqui.
• Seu tema provavelmente já tem tudo o que você precisa, consulte a documentação (se houver) e tome a liberdade de brincar à vontade com o código.

index.html

• Esta é sua homepage, cara :)

_includes

• Fragmentos reusáveis de código ou texto vão aqui. A ideia é evitar repetições desnecessárias.
• É comum que contenha o header e footer mas você pode usar para absolutamente qualquer coisa.
• Todo documento nessa pasta pode ser incluído facilmente em páginas e postagens com uma tag liquid. Exemplo: {% include xablau.html %}

_layouts

• São esquemas em HTML aplicáveis a páginas e posts.
• Para usá-los, você precisa anunciar com uma YAML front matter, um bloco simples de texto, separado por três traços, que precisa ser a primeira coisa do arquivo:

---
layout: post
title: Receita deliciosa de coxinha de jaca
---

_posts

• Aqui vão todas as suas postagens.
• Você pode escrever em markdown, que é infinitamente simples e recomendável, e usar HTML quando e se precisar.
• Os nomes dos arquivos precisam ser escritos em um formato específico:
  YYYY-MM-DD-titulo.md

Por exemplo, 2011-10-25-coxinha-de-jaca.md, informa ao Jekyll a data 25 de Outubro de 2011 e o título “coxinha de jaca”.

_site

• É nesta pasta que o Jekyll gera todos os arquivos que efetivamente serão servidos. Você pode ignorá-la sem remorso.
• Tudo aqui é constantemente reescrito, de forma que qualquer alteração que você fizer nesta pasta será perdida para todo o sempre.

5. Sirva e teste o site localmente

Navegue até a pasta do seu site e deixe o Jekyll fazer sua mágica:

cd seu-nome-de-usuario.github.io
jekyll serve --watch

Ta-dã! Você pode ver seu site em ação em http://localhost:4000.

A flag --watch é opcional e faz com que suas alterações tenham efeito automaticamente (bastando atualizar a página no navegador).

jekyll build 

6. Publique com Git

Uma vez satisfeito com as alterações, é hora de torná-las online com o Git.

Primeiro, um ajuste

Crie um arquivo de nome .gitignore, sem extensão, em sua pasta mãe com o seguinte conteúdo:

_site

Sim, só isso. Este aquivo contém tudo que você quiser, err, que o git ignore. E eu sei que você não quer que o git envie a pasta _site para o repositório (por padrão, o GitHub não precisa dela).

Agora sim, publicando

Na pasta do site, rode:

git add -A
git commit -m "minha primeira edição"
git push

Preencha seu login e senha do GitHub e tcharã, seu conteúdo está online. Confira em http://seu-nome-de-usuario.github.io.

Entendendo os comandos acima:

• git add -A “adiciona” todas as alterações que você realizou na pasta, inclusive as deletações de arquivos, modificações e arquivos novos.
• git commit -m "minha primeira edição" “confirma” essas alterações e dá um nome para o commit. Este nome entre aspas é opcional e pode ser qualquer coisa, a finalidade é você poder se orientar caso precise desfazer alguma alteração.
• git push “empurra” o commit para o repositório remoto, ou seja, seu repositório no GitHub. Caso tenha problemas com essa etapa, tente git push origin master.

Parece complicado, né? No começo é um pouco mesmo, mas, acredite, o Git vai fazer valer a pena cada minuto gasto para aprender a usá-lo. Além de permitir a integração da sua máquina com o GitHub, o Git é um poderoso software de controle de versões que vai tornar sua vida bem melhor.

Para entender mais, recomendo este guia prático e que você faça este mini-treinamento de 15 minutos. Além disso, a documentação do Git é completíssima, bem como o tutorial da Atlassian.

(Opcional / Avançado) Sincronizando o Jekyll local com o GitHub Pages

Tanto o Jekyll como o GitHub Pages sugerem que você sincronize sua instalação local do Jekyll com a usada pelo GitHub. É completamente opcional, mas isso evita que você tenha surpresas com diferenças entre o site rodado na máquina e o gerado pelo GitHub.

Note que, para isso, você vai passar a precisar sempre de acesso à internet para rodar o site localmente, mas é por uma boa causa.

É fácil:

1) Instale o Bundler.

gem install bundler

2) Crie um arquivo com o nome Gemfile (sem extensão) na pasta do seu site com o seguinte conteúdo:

source 'https://rubygems.org'

require 'json'
require 'open-uri'
versions = JSON.parse(open('https://pages.github.com/versions.json').read)

gem 'github-pages', versions['github-pages']

Caso não funcione, tente apenas com:

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

3) Navegue até a pasta e rode:

bundle install

Pronto.

A partir de agora, você precisa rodar o Jekyll com o bundle. Basta adicionar bundle exec antes de todos os comandos jekyll. Por exemplo:

bundle exec jekyll build
bundle exec jekyll serve --watch

Lembre-se de atualizar com bundle update frequentemente e você será feliz e próspero(a).

Mais opcionais

Com os passos acima você já tem todos os instrumentos que precisa para construir e manter seu site Jekyll. A seguir, indico algumas implementações que fiz em meu site e que podem ser úteis para você.

404.md

Convém fazer uma página de erro personalizada para seu site. Basta seguir as instruções do GitHub.

Tipografia é importante

Tome 10 minutos do seu tempo para ler este guia interativo de tipografia, simples, acessível e direto ao ponto.

Você já deve saber, mas nunca use preto.

Sitemap.xml

Gerar um Sitemap.xml é uma boa prática de SEO e fará com que a busca do google goste mais ainda de você. Basta seguir as instruções do David Ensinger.

Integrando comentários do Disqus com Jekyll

O Disqus é uma plataforma de comentários bem útil e fácil de implementar. Eu até testei o Muut, mas ele não é tão completo e bonitão.

Para integrar o Disqus com Jekyll, siga as instruções do Perfectly Random.

Domínio customizado

O endereço padrão do github (seu-nome-de-usuario.github.io) já é gracinha o bastante, mas caso você queira, como eu quis, ter um domínio próprio, é fácil de fazer. O site continua hospedado no GitHub pages e um servidor de DNS faz o truque com o endereço. E, claro, você precisa pagar pelo domínio.

Eu segui as instruções do Chen Jui Jing, mas sugiro que você dê uma olhada também no tutorial do Ensinger.

Adicionando Font Awesome

Font Awesome é um pacote grátis com bilhões de ícones úteis e minimalistas, customizáveis e prontos para uso. É bem facinho de implementar.

Integrando Jekyll com Reveal.js

Reveal.js é um sistema foda de criação de apresentações de slides em HTML. A integração com o Jekyll é bem descrita no site do Luu Gia Thuy. Ele só esqueceu de dizer que, se você pretende modificar os temas padrão, você precisa clonar (e não adicionar como submodule) o reveal.js à sua pasta. Você pode ter uma ideia melhor de como organizar as pastas e arquivos html dos slides no meu repositório.

Páginas de subcategorias

Pela natureza meio esquizo deste site, eu quis precisei dividir as postagens entre duas categorias, “Psicologia para concurso” e “blog”, e isso complica tudo. Depois de pesquisar bastante, fiquei satisfeito com as instruções nessa resposta no Stack Overflow.

Obs.: Em 2020, junto com a mudança do tema, achei melhor simplificar e me livrar dessa divisão. Minha vida tem sido 34,5% mais fácil desde então.

É isso

Parece muito, mas é só o começo. O universo de informação em volta do Jekyll e GitHub é gigantesco e logo logo você estará descobrindo novas soluções e ferramentas. Não se assuste com o volume de informação. Uma vez passado o susto inicial, você estará gerando sites estáticos com um estralar de dedos.

Nesse guia, eu abrangi a maior parte do que descobri até agora, mas muita coisa ficou de fora. Algo ficou mal explicado ou você empacou em alguma etapa? É só falar ;)