Customizações do blog

Plugins do pelican

As customizações que tiveram mais impacto foram provavelmente os plugins de pelican que eu adicionei. Eles não são minhas modificações, mas dada sua importância eu quero mencioná-los mesmo assim.

Os dois plugins que eu estou usando atualmente são i18n_subsites e series, e foram bem fáceis de encontrar pelo repositório de plugins.

O i18n_subsites é ótimo para o meu blog com idioma duplo. Por padrão o pelican suporta apenas traduzir artigos do blog como textos independentes, de forma que cada artigo que tenha sido traduzido possui links para as traduções. Mas o que eu realmente queria era ter duas versões do meu blog, uma em inglês e outra em português. Cada uma com toda a interface na sua própria língua além de apenas mostrar os artigos dessa língua. Esse plugin possibilita exatamente isso.

É um pouco confuso de entender como configurar corretamente no começo, principalmente a parte de localização do template, mas bom, eu aprendi sobre Jinja2 e gettext! Commits relevantes: 1 (foi parte do commit inicial...), 2, 3, 4 e 5.

O series eu adicionei um pouco depois. Ele é muito simples mas útil. A propósito você pode vê-lo em ação nesse mesmo artigo no topo. Ele é o que me permite fazer esse artigo ser parte de uma série de artigos, com link para os outros. Commits relevantes: 1.

Feed RSS separado para cada sub-site i18n

Ainda no tema de tradução, já que eu queria sub-sites separados para cada idioma, também fazia sentido ter um feed RSS para cada um deles. No fim isso acabou sendo uma mudança de uma única linha, apesar de ter demorado um pouco para eu descobrir como fazer isso. Commits relevantes: 1.

Detecção automática do idioma pelo nome do arquivo

Outra customização relacionada a tradução (foi algo bem importante pro meu blog! 😝) foi a configuração automática do idioma de um artigo com base no nome do arquivo. Já que eu já quero que o arquivo para cada tradução de um artigo tenha o idioma em seu nome, isso me poupa de ter que adicionar o cabeçalho de idioma também.

Por exemplo, os arquivos para este artigo são chamados 07-blog-custom-en.rst, para a versão em inglês, e 07-blog-custom-br.rst para a versão em português. Normalmente eu também precisaria configurar o cabeçalho de metadados lang para cada um com o idioma correspondente, mas com essa mudança ele é configurado automaticamente 🙂. Commits relevantes: 1 (de novo, parte do commit inicial 😅) e 2.

Configuração de ícone para páginas

Quando eu estava configurando a barra de navegação no topo, eu queria adicionar um ícone para cada item, para deixar bem claro o que cada um faz. Mas a página Sobre, diferentemente dos outros, é uma página gerada do fonte (assim como os artigos) e adicionada automaticamente à barra, então não é possível configurar seu ícone direto no HTML.

Para resolver isso eu criei um cabeçalho de metadado customizado icon que armazena o nome do ícone FontAwesome que será mostrado na barra para a página. Aí eu apenas adicionei o nome daquele ícone de "círculo de informação" para a página Sobre e a aparência ficou bem melhor 🙂. Commits relevantes: 1.

Conserto da renderização de literal no rst

Vamos finalizar o artigo com a maior mudança 😝.

Primeiro de tudo, um pouco de contexto: Quando eu comecei o blog, eu escrevia meus artigos em Markdown. Mas alguns meses depois eu conheci o reStructuredText (daqui para frente, chamado de rst) porque ele era usado na documentação do Kernel Linux, e comecei a usar mais ainda quando descobri o rst2pdf, que eu não vou entrar em detalhes já que ainda pretendo escrever sobre ele eventualmente. O ponto é que eu passei a escrever os meus artigos em rst já que ele também é suportado pelo pelican.

Mas um problema muito irritante que eu enfrentei foi que o gerador HTML padrão do rst traduz blocos literais para tags <tt>. Essa tag foi descontinuada no HTML5, e o mundo inteiro usa <code> para código no meio do texto, incluindo meu tema, o que significa que literais não eram renderizados corretamente. (Existem motivos para o rst não usar <code> para literais, mas para o meu blog eles não são relevantes)

Eu poderia ter simplesmente adaptado meu tema para contornar esse problema, mas isso seria apenas escondê-lo: A tag descontinuada <tt> continuaria ali para todo o mundo ver.

Em um primeiro momento, eu contornei esse problema usando o role code explicitamente:

O seguinte é um literal no rst, então ficará dentro de uma tag <tt>: ``bla``
O seguinte usa o role 'code', então ficará dentro de uma tag <code>: :code:`bla`

Essa é claramente uma sintaxe muito extensa para um blog que frequentemente usa código no meio do texto, então eu me cansei rapidamente dela. Eu comecei então a redefinir o role padrão para ser code, e a usar um único símbolo de crase ao invés dos dois que se usa para literais:

.. default-role:: code

Agora o seguinte vai usar o role 'code': `bla`

Já que o texto está entre um único símbolo de crase de cada lado mas não possui um role especificado, ele usará o padrão. Muito melhor, mas eu ainda precisava escrever aquela definição de default-role no começo de cada documento...

Finalmente, eu pensei em uma solução ainda melhor: Criar um plugin de leitor de rst para o pelican que modifique o leitor padrão apenas quando estiver lidando com literais, para que a saída seja <code> ao invés de <tt>.

Honestamente isso foi mais fácil do que eu esperava. Só precisou copiar um pouco dos leitores do pelican e do Sphinx e funcionou perfeitamente! Agora eu finalmente conseguia escrever literais usando a sintaxe padrão do rst e ver eles renderizados como <code> no HTML sem nenhum trabalho a mais 🙂. Commits relevantes: 1 e 2 (esse é apenas eu atualizando todos os textos do blog para usar a nova sintaxe).