Fa uns dies vaig activar de nou els comentaris al blog, en un article anterior explico el perquè de la reactivació.
Decidit a reactivar-los, el repte era quin sistema de comentaris utilitzar, que havia de ser independent de la pàgina, un sistema a banda.
1. Perquè un sistema a banda?
Aquesta pàgina és un lloc estàtic, d’html pur, sense cap base de dades al darrere. Bàsicament, és un conjunt de fitxers de text, cadascun amb un article, que els passo per un programa que genera la web i la publica (per a qui hi estigui interessat, hi ha una mica més de detall tècnic.)
Un sistema de comentaris és un sistema, per contra, dinàmic, on s’entra el comentari, s’ha de guardar en algun lloc i s’ha de mostrar en la mateixa pàgina.
Cal juntar dos mons diferents en un de sol, això és difícil. Per tant, cal buscar un subsistema que pugui cridar des de la pàgina, i “sembli” integrat dins del blog.
2. Requisits per un sistema de comentaris senzill, lliure i anònim
Vaig definir uns requisits, no tots tècnics, alguns son més de principis, lligats a una idea de web oberta:
- El sistema ha de ser autohostatjat.
- Sense dockerització per desplegar, via ftp (el meu hosting no permet dockerització.
- No ha de tenir dependència de cap base de dades.
- La integració ha de ser fàcil, sense gaire programació ni retocs en el codi i plantillatge de Hugo.
- Vull un sistema de text basat en fitxers, per poder recuperar els comentaris sense dependre de software extern.
- No vull sistemes de registre depenents de tercers, que obliguin possibles comentadors a registrar-se: els comentaris han de poder ser anònims.
- Possibilitat de correu d’informació si hi ha resposta (reply) a un comentari.
3. La cerca d’un sistema
Amb això en ment vaig fer una mica de recerca i vaig trobar alguns sistemes potencials, que llisto aquí sota. Tots estan buscats per tenir una integració fàcil amb Hugo, de sistemes n’hi ha molts més.
Els enllaços de sota son a articles que em van semblar interessants, no al propi sistema, i els comentaris que faig son en relació als meus requeriments, cada una de les alternatives és interessant en si mateixa.
- disqus: tot un clàssic, però depens de tercers, les dades no son teves.
- giscus (1, 2): idea, interessant… però requereix registre amb github, les dades no son teves.
- cusdis: alternativa a disqus, autohostatjable, opensource… però requereix compte a cusdis.
- comentario: No requereix registre, sembla… però la instal·lació és docker. Busco autohostatjat… més senzill.
- zooment: Pinta bé, però no veig on i com guarda les dades.
- Comentaris via bluesky: requereix registre amb Bluesky, les dades no son teves.
- Comentaris via Mastodon: requereix tenir compte amb Mastodon (qualsevol servidor) i una gestió manual del link (que amb Hugo costaria de muntar)
Aquestes sistemes, però, no complien amb alguna de les premises anteriors: o bé no permetien autohostatjament, o era difícil d’instal·lar si no tens docker, o usaven bases de dades o demanaven inscripció… o unes quantes alhora.
4. El sistema escollit: HashOver
Finalment vaig trobar HashOver, un projecte de Jakob Barkdull on implementa un sistema de comentaris basat totalment en fitxers de text, en aquest cas, en format xml.
El sistema té tot allò que vull:
- Comentaris basats en fitxers, llegibles per humans, i sense necessitar software de tercers.
- No cal cap registre en cap plataforma, els comentaris poden ser anònims.
- S’integra fàcilment amb Hugo, i va totalment a banda. No modifica la instal·lació original.
- Més enllà de com s’integra, puc seguir generant la meva pàgina i el blog com sempre. Zero interferència
- El projecte és robust, lliure i usable per tothom.
- Usa PHP com llenguatje d’implementació, extès i senzill.
La versió que he escollit és la 1.0. En Jakob té una altra versió (encara en desenvolupament), però amb estructura més complicada i que implementa utilitats que no em son necessàries. Valoro molt la senzillesa, aquí: allò que em cal i res més.
La resta de l’article explica com integro HashOver amb Hugo.
5. Instal·lació de Hashover amb Hugo, pas a pas
Segurament es pot fer d’alguna altra manera, però aquesta m’ha funcionat prou bé.
5.1 Modificació de config.toml
Dintre del fitxer config.toml, secció [Params], he definit un nou paràmetre, hashover:
[Params]
subtitle = ""
mainSections = ["blog"]
... normal stuff of config.toml
custom_css = "css/custom.css"
comments = true
hashover = true #indicates that comments with hashover are on
Els paràmetres comments i hashover cal definir-los com true. El paràmetre hashover no es estàndar de Hugo, però no he volgut reusar alguns que ja porta de base per integrar altres sistemes, com disqus.
5.2 Integració a la plantilla single.html
A la plantilla singhle. html, afegeixo el següent codi:
<!-- leave tag comments:false en pages weith no commenting -->
{{ if $.Param "comments" }}
{{ if .Site.Params.hashover }}
<div class="hashover-comments">
{{ partial "hashover-comments.html" . }}
</div>
{{ end }}
{{ end }}
{{ if $.Param "showRelatedPosts" }}
...
L’he posat sobre el bloc de codi de showRelatedPosts.
5.3 Plantilla de hashover-comments.html
Defineixo una nova plantilla hashover-comments.html a layouts\partials, amb el següent codi:
<section class="js-comments staticman-comments">
<div id="hashover"></div>
<script type="text/javascript">
var passwd_on="no"; // Disables "Password" field
</script>
<script type="text/javascript" src="/hashover/comments.php"></script>
<noscript>Heu de tenir el Javascript habilitat per poder comentar.</noscript>
</section>
5.4 Desplegament del directori de comentaris
A l’arrel de la pàgina web (public_html), he desplegat el codi descarregat de hashover, seguint les instruccions d’en Jakob. Jo he usat el mètode d’integració via javascript, no php.
Per la resta, no té cap dificultat.
4.1 Desplegament de la pàgina i esborrat del directori
Si quan genereu el site amb Hugo el pujeu via rsync o amb algun automatisme, incloeu una comanda --exclude per no esborrar la carpeta de hashover.
Si ho feu via ftp, no esborreu la carpeta.
5.5 Modificació de les capçaleres yaml dels fitxers md
Cal afegir el següent comentari a les capcaleres Frontmatter dels fitxers markdown en generar el site:
Fitxers md (article on si volem comentaris)
---
title: Titol d'article d'exemple
date: 2025-12-24T14:13:59+0200
summary: Un resum de l'article
comments: true # tambe podem no posar la línia i per defecte és true
---
Fitxer md (pagina on no volem comentaris)
---
title: Pàgina d'exemple
date: 2025-12-24T14:13:59+0200
lastMod: 2026-07-27
summary: Resum de la pàgina
showPageDates: true
comments: false
---
5.6 Entenent l’estructura de carpetes i el funcionament
Hashover deixa els comentaris en la carpeta hashover/pages.
Per cada pàgina crea un directori amb el nom de la pàgina i dins els fitxers 1.xml, 2.xml, etc. amb els comentaris que s’hagin fet.
Per cada pàgina que es visita, hashover crea un directori, encara que sigui buit. Si mireu l’estructura de carpetes, en veureu moltes buides.
6. Modificacions a Hashover
Si mireu el disseny del formulari de comuntaris a qualsevol article d’aquest blog, veureu que NO és l’original de Hashover.
Jo hi he fet unes quantes modificacions, a nivell de CSS i de visualització dels fils de comentaris, per adeqüar-lo més a les meves necessitats i al disseny que jo volia.
No obstant, el sistema que proveeix Jakob és perfectament operatiu i seguint les passes anteriors s’integra a la primera.
Si voleu el codi font del que jo he integrat, el teniu a github (v1.0.0). Però ja és part d’un altre projecte, HashOver-md, per usar Markdown en comptes de xml per desar comentaris. Veurem com avança.