[🛠] Transformando as notas de rodapé do blog GitHub Pages em popovers

✨ Resumo do GPT-5.5 　

Um registro de como reduzi o atrito das notas de rodapé padrão do Kramdown, que levavam o leitor do corpo do texto para as referências no fim da página, mantendo a estrutura existente e transformando os links de nota no corpo em uma UI de popover no formato [1].

Assim que comecei a usar notas de rodapé de verdade, o incômodo apareceu.

Quando trato de artigos externos ou materiais de referência no blog, agora coloco footnotes do Kramdown ao lado do trecho relevante no corpo. Em um post como A escassez inédita de cédulas, a raiva e o prejuízo causado por extremistas, havia muitos fatos a sustentar, então as notas também eram numerosas.

Mas, ao ler de fato, o fluxo não era bom.

Ao clicar no número da nota no corpo do texto, não aparecia um popup. A página descia até a área de Referências no fim. Como comportamento padrão, isso faz sentido. O Kramdown cria notas de rodapé assim mesmo. Mas em um texto longo é fácil perder o ponto onde eu estava lendo.

O formato do número da nota também era ruim.

Quando aparecem apenas números pequenos como 1 2 3 4, fica difícil clicar. No celular, ainda mais. Acertar com precisão um número pequeno no meio do texto exige mais atenção do que deveria.

Então desta vez mudei um pouco o sistema de notas.

No corpo, elas agora aparecem como [1], [2], [3], e ao clicar abrem um pequeno popover em vez de levar a página para o fim.

Não mexi na estrutura do Kramdown

Desde o início eu não queria mudar a sintaxe Markdown nem a forma como as footnotes são geradas.

Hoje escrevo as notas assim.

Frase do corpo.[^source]

[^source]: Descrição da fonte e link

Esse método deve continuar.

Do lado da escrita, uso uma sintaxe próxima do padrão Markdown, e quando o Jekyll faz o build, o Kramdown gera o HTML das notas. A área de Referências no fim também permanece. Se eu trocasse toda essa estrutura, teria de mexer em posts existentes e também nas traduções.

Por isso, a regra deste trabalho foi simples.

Manter o formato de escrita como está.
Manter as notas inferiores geradas pelo Kramdown.
Mudar apenas a exibição e o comportamento de clique dos links de nota no corpo.

Ou seja, manter os dados originais e o fallback, e melhorar só a experiência de leitura.

Fiz os números parecerem [1]

Primeiro mudei o CSS.

O Kramdown adiciona a classe a.footnote aos links de nota no corpo. Transformei esse link em um pequeno botão inline-flex e adicionei os colchetes com ::before e ::after.

Como resultado, no corpo aparece isto em vez de apenas um número.

[1] [2] [3]

Também aumentei um pouco a área clicável.

Se parecer um botão chamativo, quebra o ritmo do texto. Mas se continuar sendo só um número minúsculo, é difícil clicar. Então coloquei uma borda e um fundo bem sutis, mantendo o texto menor que o corpo.

Como este blog tem modo claro e modo escuro, não deixei as cores fixas. Usei as variáveis Sass já existentes.

$primary-color
$background-color
$border-color
$text-color

Este blog já carrega customOverride.scss depois das skins clara e escura. Por isso, adicionei o estilo das notas em _sass/custom/customOverride.scss, sem mexer diretamente no código original do tema.

O clique cria um popover

Depois veio o JavaScript.

Antes, o SmoothScroll estava ligado a todos os links #hash. Um link de nota também é, no fim, um link interno para algo como #fn:..., então ao clicar a página descia suavemente.

Desta vez interceptei primeiro apenas os links de nota dentro do corpo.

O alvo é este.

.page__content a.footnote[href^="#fn"]

Ao clicar, o script bloqueia o movimento hash original, encontra o conteúdo já renderizado na lista inferior de notas e clona esse conteúdo. Dentro da nota inferior existe um link reversefootnote para voltar ao corpo, mas dentro do popover ele não é necessário, então removi.

O fluxo é este.

Clicar na nota do corpo
-> ler o target id a partir do href
-> encontrar o footnote li inferior
-> clonar o conteúdo
-> remover reversefootnote
-> inserir no popover
-> calcular a posição perto do link da nota

Como o hash não é alterado, a URL não fica suja. A página também não desce para o fim.

Há três formas de fechar.

Clicar na mesma nota novamente
Clicar fora do popover
Esc ou o botão de fechar

Para uso com teclado, também adicionei aria-haspopup="dialog" e aria-expanded. O próprio popover usa role="dialog". Não é algo que eu chamaria de componente de acessibilidade perfeito, mas é melhor do que uma div flutuante sem semântica.

Mantive tudo dentro da tela no celular

A posição é importante em um popover de nota.

Mostrar logo abaixo do link no corpo parece natural, mas perto da borda direita ou em largura mobile ele pode sair da tela facilmente.

Por isso, ao calcular a posição, forço uma margem dentro do viewport.

Mínimo de 12px à esquerda
Mínimo de 12px à direita
Se faltar espaço embaixo, mostrar acima
Se ainda faltar, fazer clamp para dentro do viewport

A largura do popover também não é fixa.

width: min(30rem, calc(100vw - 1.5rem));

No desktop, ele não fica largo demais. No celular, não fica maior que a tela.

Também coloquei max-height e overflow: auto para notas longas. A intenção é evitar que o popover cubra a tela inteira quando o título de um artigo externo ou um link é comprido.

Também atualizei o arquivo minificado

Neste blog, assets/js/_main.js é o arquivo-fonte, e o site publicado lê assets/js/main.min.js.

Então, depois de alterar o JS, regenerei o arquivo minificado e o source map com a task do Rake.

bundle exec rake js

Se eu esquecer isso, a fonte local pode estar corrigida enquanto o site real continua servindo o JavaScript antigo. Nesse tipo de trabalho, o arquivo-fonte e o arquivo de publicação precisam ser vistos juntos.

O que confirmei

Confirmei assim.

node --check assets/js/_main.js
bundle exec rake js
bundle exec jekyll build

Depois abri, por um servidor estático local, um post real com muitas notas de rodapé.

Confirmei estes pontos.

Os links de nota aparecem como [1]?
O hash da URL permanece igual depois do clique?
A página deixa de pular para as referências no fim?
O popover aparece?
O popover contém o conteúdo da nota inferior?
Em largura mobile, o popover fica dentro da tela?

No desktop, as notas inferiores estavam bem abaixo no documento, mas após clicar em uma nota o scroll ficou perto do corpo. Em largura mobile, o popover também ficou dentro da tela.

É uma função pequena, mas muda bastante a leitura

Este trabalho não é uma grande função.

Não há modelo de dados, nem roteamento, nem página nova. É apenas deixar os links de nota existentes mais visíveis e abrir um popover ao clicar.

Mesmo assim, a sensação de leitura muda bastante.

Especialmente em posts com muitos fatos, notas de rodapé não são decoração. Quando o leitor pensa “de onde saiu isso?”, ele precisa conseguir conferir na hora. Se, para conferir, ele for jogado para o fim do texto e depois tiver de voltar ao corpo, a nota vira rapidamente algo incômodo.

Agora, lendo o corpo, dá para clicar em [1], conferir e fechar.

A área inferior de Referências continua lá. Quem quiser revisar todas as fontes no fim do texto ainda pode rolar até lá.

Era isso que eu queria.

Manter a forma de escrever em Markdown. Manter a estrutura padrão do Jekyll/Kramdown. Só cansar menos os dedos e os olhos de quem lê.

Mesmo pequenas, melhorias assim precisam continuar se acumulando no blog.