Renvois

Renvoyer un lecteur vers une autre page a l’air d’être un seul problème. C’en est trois, et pendant un temps ce site les a résolus de quatre façons différentes: une liste en front matter sur un billet, des lignes « Companion note: » tapées à la main sur quatre autres, une flèche dans les tableaux de données, et des « voir aussi » improvisés au gré de l’envie. Rien n’imposait la cohérence, donc rien n’était cohérent.

Il y a désormais trois mécanismes, choisis selon ce à quoi sert le renvoi.

related: — la liste de fin de page#

Une liste de chemins en front matter produit un bloc Billets liés après le contenu.

related:
  - /docs/site-implementation/shortcodes/callouts/
  - /docs/site-governance/content/markdown/

Les chemins sont indépendants de la langue. Chaque site linguistique les résout sur ses propres pages: la liste identique va donc dans le front matter du .en.md et du .fr.md — ce qui est bien l’objectif, puisque la version précédente, tenue à la main, n’existait qu’en anglais et que les pages françaises n’affichaient silencieusement rien.

Deux comportements délibérés:

Toutes les entrées sont affichées. Une version antérieure plafonnait la liste à trois, sans le dire. Le billet qui atteignait ce plafond en comptait quatre, et la quatrième, masquée, pointait vers une page inexistante: la troncature dissimulait donc un lien mort.

Les chemins non résolus déclenchent un avertissement à la compilation. Notez qu’une page en draft: true ne se résout pas: pointer vers un brouillon non publié est signalé comme manquant plutôt qu’ignoré en silence.

companion — le renvoi en haut de page#

Il arrive que le lecteur ait besoin d’une page avant celle-ci, et qu’il doive savoir pourquoi. Ce n’est pas une liste; c’est la phrase qui a de la valeur.

{{< companion "/blog/rustdesk/self-hosting/" >}}
explique l’architecture et les compromis côté serveur derrière ce guide d’installation.
{{< /companion >}}

Le rendu est un encart discret marqué ↩︎ au-dessus du contenu: l’étiquette, le titre de la page liée, puis votre phrase. Les guides d’installation s’en servent pour renvoyer au billet d’architecture, ce qui leur permet de rester des guides au lieu de réexpliquer la conception.

Hugo résout le chemin à la compilation et fait échouer la construction s’il est mauvais: une coquille est détectée tout de suite plutôt que publiée en lien mort.

backLink — la flèche des tableaux#

Les pages /uses, /projects et /publications sont construites à partir de YAML, et une ligne de tableau n’a pas de place pour de la prose. Un backLink sur une entrée ajoute un ↩︎ en exposant après le nom, pointant vers la note liée:

- name: chezmoi
  backLink: /til/chezmoi/

La règle#

Deux règles empêchent tout cela de proliférer à nouveau.

Un renvoi relève de la navigation, pas de la gravité. Il reste visuellement discret — sans fond, sans couleur. Les encadrés sont le mécanisme bruyant, réservé au contenu qui change ce que le lecteur doit faire. Une note compagnon déguisée en avertissement dévalue les vrais avertissements.

↩︎ signifie toujours « contenu lié ». C’est le symbole commun aux notes compagnons et aux lignes de tableau: la même marque a le même sens partout où elle apparaît.

Un cas reste délibérément en prose: une ligne qui renvoie à des sources externes est une citation, non un renvoi interne, et sa place est dans le texte, là où le lecteur voit ce sur quoi il clique.