Archétypes de section

Chaque archétype ci-dessous définit ce qu’est un type de section — à quoi il sert, ce qui y appartient, ce qui n’y appartient pas, et ses règles de fonctionnement — indépendamment d’un site en particulier, pour qu’un nouveau site (personnel, consultation, code ouvert) puisse l’adopter sans avoir à trancher de nouveau.

Blogue#

Pour: les essais, les annonces, les traces de ce qu’on pensait à un moment précis — et les notes techniques entretenues comme documents vivants.

Les blogues traditionnels sont linéaires: les nouveaux billets apparaissent en haut, les anciens descendent dans l’archive, et chaque entrée est traitée comme une version finale et polie. Ce modèle convient encore aux essais, aux annonces et aux instantanés d’opinion. Il ne convient pas à toutes les pages: certaines notes ressemblent davantage à un jardin numérique, où une idée commence comme une graine, accumule des liens, devient un AJA, grandit en billet, puis parfois devient une collection. Ce modèle préfère le travail en cours à la mise en scène d’une image trop lisse.

Règles de fonctionnement des documents vivants:

• Une note technique ne devrait pas prétendre être finale. Les valeurs par défaut changent, les outils changent, les modèles de menace changent; la bonne posture une année peut avoir besoin d’être taillée deux ans plus tard.
• Rendre les deux dates visibles. Créé est le moment où la note est devenue publique; Mis à jour est le moment où le contenu a changé de façon substantielle. Le front matter contient à la fois date et lastmod: la date de création garde la provenance, la date de mise à jour indique si la page est encore entretenue.
• Les modifications discrètes ne font que mettre lastmod à jour. Corriger une faute, améliorer une phrase ou ajouter une référence ne demande aucun rituel.
• Ajouter un journal des changements quand le lecteur peut se soucier de ce qui a changé: une recommandation de sécurité a changé, une commande ou une configuration a été remplacée, la page recommande maintenant un outil différent, ou un ancien conseil a été retiré parce qu’il est devenu dangereux, trompeur ou obsolète. Dans ces cas-là, la page ne devrait pas cacher son évolution — le journal des changements fait partie du modèle de confiance.
• Evergreen ne veut pas dire statique. Une page vraiment evergreen reste utile parce qu’elle peut être revisitée, corrigée, enrichie et parfois élaguée. Ajouter un lien quand la source est petite, écrire un AJA quand la leçon est autonome, en faire un billet quand il faut plus de contexte, en faire une collection quand l’idée devient une petite carte.

Un blogue peut être evergreen s’il cesse de prétendre que chaque billet est un artefact scellé. Certaines pages devraient rester des essais; d’autres devraient être des jardins entretenus — datés, mis à jour, liés et autorisés à grandir publiquement.

AJA (aujourd’hui j’ai appris)#

Pour: les petits apprentissages qui ne méritent pas le rituel d’un billet complet. Un carnet public, pas une archive d’articles polis.

Le format est volontairement court: une chose, quelques lignes, assez de contexte pour qu’un futur lecteur comprenne pourquoi c’était utile. Les entrées capturent ce qu’on apprend en construisant des systèmes, en déboguant des déploiements, en lisant de la documentation ou en essayant des outils — la commande exacte, le drapeau, le message d’erreur, le réglage ou le modèle mental qui serait autrement oublié dans trois mois.

• Y appartient: tout ce qui est autonome et trop petit pour un billet complet. Le seuil de publication est volontairement plus bas que celui du blogue, pour que les petites découvertes soient documentées au lieu d’être perdues.
• N’y appartient pas: ce qui a besoin d’un vrai contexte — cela grandit plutôt en billet de blogue.
• Le brouillon est acceptable. Une note utile aujourd’hui vaut mieux qu’un essai parfait qui ne sera jamais écrit.
• Les notes récentes en premier, faciles à parcourir ensuite — assez pratiques pour servir de mémoire externe.

Le modèle vient de la microsection TIL de Julia Evans et du site TIL de Simon Willison.

Collection#

Pour: regrouper des billets liés qui vont ensemble sans mériter une nouvelle section de premier niveau — par exemple, une trace continue des décisions sur un même sujet.

Le mécanisme est une seule clé de front matter:

collection: "hugo"

Le gabarit d’un billet vérifie cette valeur. Quand elle existe, Hugo trouve les autres pages régulières avec la même collection, les trie par date, puis affiche une liste compacte sous l’article. La page courante reçoit aria-current="page", ce qui rend aussi la liste plus claire pour les technologies d’assistance.

• Les billets restent des billets ordinaires à des URL stables; la collection ne change rien au modèle d’URL.
• La collection n’est qu’une métadonnée jusqu’au moment où un gabarit décide de l’utiliser — pas de type de contenu personnalisé, de taxonomie parallèle ou de gabarit spécial pour chaque série.
• Un dossier n’est pas une série. Un sous-répertoire rend le dépôt plus facile à parcourir, mais il ne crée pas de série sémantique; les pages appartiennent encore à leur section.
• Promouvoir seulement quand elle grandit. Une collection qui devient plus ambitieuse peut être promue plus tard: une section dédiée, une page d’accueil de collection ou un guide édité à la main. Commencer avec le front matter garde les URL durables et réduit l’entretien.

La règle: utiliser une collection quand des billets devraient être lus ensemble, mais doivent encore se comporter comme des billets ordinaires.

Maintenant / Avant#

Pour: répondre à la question qu’un ami poserait en reprenant contact — qu’est-ce qui retient ton attention ces temps-ci?

La page Maintenant, une idée de Derek Sivers avec nownownow.com, est un petit état de situation: ce qui se construit, ce qui s’apprend, ce qui prend de l’énergie, ce qui est en pause. Ce n’est pas une biographie, ni un CV, ni une trousse média, ni un fil social.

La page Avant est la pièce complémentaire. Une page Maintenant est utile au présent, mais ses anciennes versions deviennent une archive discrète des priorités dans le temps: le travail courant devant, les anciens instantanés déplacés dans l’archive Avant, gardée facile à parcourir en grandissant (les accordéons fonctionnent bien).

Le but n’est pas de documenter tous les détails de vie — c’est de laisser assez de contexte pour que les amis, les collaborateurs et un futur soi comprennent dans quelle saison c’était.

Colophon#

Pour: dire de quoi le site est fait et pourquoi. Dans un livre, le colophon décrit la typographie, l’imprimeur, le papier et les détails de production; sur un site, il explique la pile technique, l’hébergement, les polices, les choix d’analytique et les valeurs qui ont guidé la construction.

• Pas seulement une liste de pièces. Un colophon est une courte déclaration de principes: des choix comme éviter le suivi côté client, héberger les polices localement, publier en deux langues ou préférer Markdown et des fichiers de données à des systèmes cachés devraient être visibles quelque part.
• L’accompagner d’un humans.txt — une petite convention web lisible qui dit qui a fabriqué une chose et de quoi elle est faite.
• Alimenter les pages récurrentes avec des données partagées. Les pages maintenant, uses, colophon et humans.txt peuvent partager des données YAML structurées, ce qui garde le site facile à maintenir en deux langues sans transformer chaque mise à jour de contenu en modification de gabarit.

Wiki#

Pour: une référence à auteur unique faite de pages thématiques densément interreliées — organisée par sujet, pas par chronologie. Un générateur de site statique suffit: pas d’auteurs multiples, pas de révisions de pages, pas de serveur de base de données.

Les exigences qui définissent l’archétype:

• Liens vers l’avenir libres. En écrivant une page, faire un lien vers des pages thématiques qui existeront plus tard, sans se soucier de savoir si elles existent maintenant.
• Liens manquants visibles. Un lien vers une page qui n’existe pas encore reçoit un style distinct (par exemple rouge au lieu de bleu) et se met à jour automatiquement une fois la page créée.
• Une page commune « à venir ». Les liens manquants aboutissent sur une seule page d’attente plutôt que sur une 404; le comportement 404 normal du site reste intact.
• Écriture en Markdown simple, y compris la coloration syntaxique du code.

La mécanique Hugo, adaptée de « Repurposing Hugo as a wiki » de Justin Miller:

Activer le HTML en ligne dans les shortcodes et rendre non fatales les références non résolues, dirigées vers la page manquante commune:

markup:
  goldmark:
    renderer:
      unsafe: true

refLinksErrorLevel: WARNING
refLinksNotFoundURL: /pages/missing/

Un shortcode link prend un argument quand le slug de la page correspond au mot cliquable, deux quand le texte du lien diffère:

{{% link other %}}
{{% link "my text here" other2 %}}

Le shortcode lui-même, layouts/shortcodes/link.html:

{{- $link := (urls.RelRef . (cond (eq (len .Params) 2) (.Get 1) (.Get 0))) -}}
<a href="{{ $link }}"{{ if eq $link (urls.RelRef . "missing") }} class="missing"{{ end }}>{{ .Get 0 }}</a>

Parce qu’il résout avec urls.RelRef, les liens sont indépendants du nom de fichier et des réorganisations: un argument other trouve other.md, ou tout fichier dont le front matter définit slug: other, peu importe où il déménage. Quand la résolution échoue, la page manquante est liée et la classe CSS missing est appliquée:

main#content a.missing {
  color: #f00;
}

Un défaut connu: le nom missing est dupliqué entre le shortcode et la configuration du site, parce qu’aucune fonction Hugo n’expose la valeur configurée de refLinksNotFoundURL.