Cómo habilitar comentarios en el blog con Giscus

Hoy he añadido un sistema de comentarios al blog basado en Giscus, una herramienta que permite a los lectores comentar los artículos sin que sea necesario que abandonen el sitio.

¿Por qué Giscus?¶

Giscus es una alternativa a sistemas de comentarios tradicionales como Disqus. Sus principales ventajas son:

Gratuito y sin publicidad — no hay rastreadores de terceros
Basado en GitHub Discussions — los comentarios se guardan en tu repositorio, bajo tu control
Moderación incluida — puedes revisar y aprobar comentarios desde GitHub
Notificaciones por email — recibes alertas automáticas cuando alguien comenta
Respeta el tema del sitio — se adapta al modo claro/oscuro automáticamente
Soporte multiidioma — he configurado el español como idioma por defecto.
No he encontrado de momento una alternativa que no dependa de Github y sea sencilla de implementar. Usaré este sistema mientras investigo alternativas.

Pasos que dimos¶

1. Instalar la app Giscus en GitHub¶

Primero accedimos a https://github.com/apps/giscus e instalamos la app en el repositorio asociado a la web: ichigar/web. Esto permite que Giscus acceda a las Discussions del repositorio.

2. Crear una categoría en GitHub Discussions¶

Luego activamos GitHub Discussions en el repositorio y creamos una categoría llamada "Comentarios" específicamente para los comentarios del blog.

https://github.com/ichigar/web/discussions

3. Configurar Giscus¶

En https://giscus.app rellenamos:

Repository: ichigar/web
Page ↔ Discussion mapping: pathname (cada URL del blog es un hilo de Discussion separado)
Discussion category: Comentarios
Theme: preferred_color_scheme (respeta el tema claro/oscuro del navegador)
Language: es (español)

Giscus genera un snippet JavaScript que incluye los identificadores únicos del repositorio y la categoría.

4. Integrar en MkDocs¶

MkDocs Material tiene soporte nativo para comentarios. Solo hay que crear un archivo overrides/partials/comments.html:

{% if page.meta.get("comments", true) and page.file.src_path.startswith("blog/posts/") %}
<h2 id="comentarios">Comentarios</h2>
<script src="https://giscus.app/client.js"
        data-repo="ichigar/web"
        data-repo-id="R_kgDORe_H0g"
        data-category="Comentarios"
        data-category-id="DIC_kwDORe_H0s4C6YH-"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="es"
        crossorigin="anonymous"
        async>
</script>
{% endif %}

La condición Jinja2 asegura que los comentarios solo aparezcan en los posts del blog, no en otras páginas.

Cómo funciona ahora¶

Lectura de comentarios: cualquiera puede leer los comentarios sin necesidad de cuenta
Publicación: los usuarios necesitan una cuenta de GitHub para escribir comentarios
Moderación: los comentarios aparecen automáticamente, pero puedes editarlos, ocultarlos o eliminarlos desde GitHub Discussions
Notificaciones: recibes un email cada vez que alguien publica un nuevo comentario

¿Te gusta cómo funcionan los comentarios? Cuéntame tu opinión