[🛠] Convertir las notas al pie del blog en GitHub Pages en popovers

✨ Resumen de GPT-5.5 　

Un registro de cómo reduje la fricción de las notas al pie por defecto de Kramdown, que saltaban desde el cuerpo hasta las referencias del final, manteniendo la estructura existente y convirtiendo los enlaces de notas del cuerpo en una UI de popover con formato [1].

En cuanto empecé a usar notas al pie de verdad, la incomodidad se hizo evidente.

Cuando trato artículos externos o materiales de referencia en el blog, ahora pongo footnotes de Kramdown junto al texto correspondiente. En una entrada como La escasez inédita de papeletas, la rabia y el daño de los extremistas, había muchos hechos que respaldar, así que también había bastantes notas.

Pero al leerla, el flujo no se sentía bien.

Al pulsar un número de nota en el cuerpo, no aparecía un popup. La página bajaba hasta la sección de Referencias al final. Como comportamiento por defecto, tiene sentido. Kramdown crea las notas al pie así. Pero en un texto largo, es fácil perder el punto donde estaba leyendo.

La forma de los números tampoco ayudaba.

Si solo aparecen números pequeños como 1 2 3 4, son difíciles de pulsar. En móvil todavía más. Tocar con precisión un número pequeño flotando en medio del texto exige más atención de la que debería.

Así que esta vez cambié un poco el sistema de notas.

En el cuerpo ahora se ven como [1], [2], [3], y al pulsarlas aparece un pequeño popover en vez de mover la página al final.

No cambié la estructura de Kramdown

No quería cambiar la sintaxis Markdown ni la forma en que se generan las footnotes.

Ahora escribo las notas así.

Frase del cuerpo.[^source]

[^source]: Descripción de la fuente y enlace

Ese método debe mantenerse.

Desde el lado de la escritura, uso una sintaxis cercana al estándar de Markdown, y cuando Jekyll construye el sitio, Kramdown genera el HTML de las notas. La sección de Referencias al final también queda intacta. Si cambiara toda esa estructura, tendría que tocar también las entradas existentes y las traducciones.

Por eso el criterio de este trabajo fue simple.

Mantener igual la forma de escribir.
Mantener las notas inferiores generadas por Kramdown.
Cambiar solo la visualización y el comportamiento de clic de los enlaces de nota en el cuerpo.

Es decir, conservar los datos originales y el fallback, y mejorar solo la experiencia de lectura.

Hice que los números se vieran como [1]

Primero cambié el CSS.

Kramdown añade la clase a.footnote a los enlaces de nota en el cuerpo. Convertí ese enlace en algo parecido a un pequeño botón inline-flex y añadí los corchetes con ::before y ::after.

Como resultado, en el cuerpo ya no se ve solo un número, sino esto.

[1] [2] [3]

También amplié un poco el área pulsable.

Si parece un botón demasiado fuerte, rompe el ritmo del texto. Pero si sigue siendo un número diminuto, cuesta pulsarlo. Así que añadí un borde y un fondo muy sutiles, manteniendo la letra más pequeña que el cuerpo.

Como este blog tiene modo claro y modo oscuro, no fijé los colores a mano. Usé las variables Sass existentes.

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

Este blog ya carga customOverride.scss después de las skins clara y oscura. Por eso añadí el estilo de notas en _sass/custom/customOverride.scss, sin tocar directamente el código original del tema.

Al hacer clic, se crea un popover

Después vino JavaScript.

Antes, SmoothScroll estaba conectado a todos los enlaces #hash. Un enlace de nota también es, al final, un enlace interno hacia algo como #fn:..., así que al pulsarlo la página bajaba suavemente.

Esta vez intercepté primero solo los enlaces de nota dentro del cuerpo.

El objetivo es este.

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

Al hacer clic, se bloquea el movimiento hash original, se busca el contenido ya renderizado en la lista inferior de notas y se clona. Dentro de la nota inferior hay un enlace reversefootnote para volver al cuerpo, pero dentro del popover no hace falta, así que lo eliminé.

El flujo es este.

Clic en una nota del cuerpo
-> leer el target id desde href
-> encontrar el li de footnote inferior
-> clonar el contenido
-> eliminar reversefootnote
-> insertarlo en el popover
-> calcular la posición cerca del enlace de nota

Como no se cambia el hash, la URL no se ensucia. La página tampoco baja hasta el final.

Hay tres formas de cerrarlo.

Volver a pulsar la misma nota
Pulsar fuera del popover
Esc o el botón de cerrar

Para el uso con teclado también añadí aria-haspopup="dialog" y aria-expanded. El propio popover usa role="dialog". No diría que es un componente de accesibilidad perfecto, pero al menos es mejor que un div flotante sin semántica.

Evité que se saliera de la pantalla en móvil

La posición es importante en un popover de notas.

Mostrarlo justo debajo del enlace del cuerpo se siente natural, pero cerca del borde derecho o en anchos móviles puede salirse fácilmente de la pantalla.

Por eso, al calcular la posición, fuerzo un margen dentro del viewport.

Mínimo 12px a la izquierda
Mínimo 12px a la derecha
Si no hay espacio abajo, mostrarlo arriba
Si aun así falta espacio, ajustarlo dentro del viewport

El ancho del popover tampoco es fijo.

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

En escritorio no se vuelve demasiado ancho, y en móvil no supera el ancho de la pantalla.

También añadí max-height y overflow: auto para notas largas. La idea es que, aunque el título de un artículo externo o un enlace sea largo, el popover no cubra toda la pantalla.

También actualicé el archivo minificado

En este blog, assets/js/_main.js es la fuente, y el sitio desplegado lee assets/js/main.min.js.

Así que después de cambiar el JS, regeneré el archivo minificado y el source map con la tarea de Rake.

bundle exec rake js

Si se olvida eso, la fuente local puede estar corregida mientras el sitio real sigue sirviendo el JavaScript antiguo. En este tipo de trabajo, hay que mirar juntos el archivo fuente y el archivo de despliegue.

Lo que comprobé

Lo comprobé así.

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

Luego abrí con un servidor estático local una entrada real con muchas notas.

Comprobé estos puntos.

Si los enlaces de nota se muestran como [1]
Si el hash de la URL no cambia después del clic
Si la página no salta a las referencias del final
Si aparece el popover
Si el popover contiene el contenido de la nota inferior
Si el popover queda dentro de la pantalla en ancho móvil

En escritorio, las notas inferiores estaban muy abajo en el documento, pero después de pulsar una nota el scroll se quedó cerca del cuerpo. En ancho móvil, el popover también quedó dentro de la pantalla.

Es una función pequeña, pero cambia bastante la lectura

Este trabajo no es una función enorme.

No hay modelo de datos, ni routing, ni página nueva. Solo hace que los enlaces de nota existentes se vean mejor y abran un popover al pulsarlos.

Pero la sensación al leer cambia bastante.

Especialmente en entradas con muchos hechos, las notas no son decoración. Cuando un lector piensa “¿de dónde sale esto?”, debería poder comprobarlo de inmediato. Si para comprobarlo lo mandas al final del artículo y luego tiene que volver al cuerpo, las notas se vuelven molestas muy rápido.

Ahora, mientras lee el cuerpo, puede pulsar [1], comprobar la fuente y cerrarla.

La sección inferior de Referencias sigue ahí. Quien quiera revisar todas las fuentes al final todavía puede bajar.

Eso era lo que quería.

Mantener la forma de escribir Markdown. Mantener la estructura base de Jekyll/Kramdown. Hacer que los dedos y los ojos del lector se cansen un poco menos.

Pequeñas mejoras como esta también tienen que seguir acumulándose en el blog.