Shortcodes

Les shortcodes permettent aux personnes qui rédigent d’utiliser une présentation réutilisable dans Markdown sans écrire de HTML brut. La référence Shortcodes documente chaque shortcode local; cette page explique quand et comment en créer un.

Les shortcodes natifs ne figurent pas dans l’inventaire local#

Hugo fournit des shortcodes natifs à l’extérieur de layouts/shortcodes/; ils ne figurent donc pas dans l’inventaire local des shortcodes. Celui qui compte ici est relref, qui résout un lien interne à la compilation :

[Encadrés]({{< relref "/docs/site-implementation/shortcodes/callouts" >}})

Préférez relref à une URL tapée à la main pour deux raisons : il fait échouer la compilation lorsqu’un chemin de contenu est mauvais, et il suit le chemin de contenu lorsque les règles de permalien changent ou qu’une section aplatit ses répertoires.

Donnez-lui toujours un chemin de contenu absolu. Un simple nom de fichier ne fonctionne que jusqu’à ce qu’un fichier soit déplacé ou qu’un nom entre en collision.

Écrire au sujet des shortcodes#

Pour afficher un shortcode sans l’exécuter, placez /* et */ à l’intérieur de ses accolades :

{{< callout type="archive" >}}

Il s’agit de la syntaxe de l’analyseur Hugo, et non d’un shortcode; elle ne figure donc pas dans l’inventaire. Utilisez-la dans la documentation, y compris pour chaque exemple de cette page.

Réutiliser un partial depuis un shortcode#

Conservez le rendu partagé dans un partial, puis appelez ce partial depuis un shortcode. Le même HTML peut ainsi servir le contenu Markdown par le shortcode et les mises en page par le partial.

Créer le partial#

Créez layouts/partials/card.html :

<div class="card">
  <h3>{{ .title }}</h3>
  <p>{{ .description }}</p>
</div>

Créer le shortcode#

Créez layouts/shortcodes/card.html, lisez ses paramètres nommés et transmettez uniquement le contrat du partial :

{{ $title := .Get "title" }}
{{ $description := .Get "desc" }}

{{ partial "card.html" (dict "title" $title "description" $description) }}

Passez . lorsque le partial a besoin du contexte complet du shortcode, ou passez .Inner lorsqu’un shortcode englobant a besoin de son contenu interne. Conservez des valeurs attendues explicites pour le partial lorsqu’un contrat plus petit suffit.

L’appeler depuis Markdown#

La rédaction peut ensuite utiliser le shortcode dans tout fichier Markdown :

{{< card title="Hello World" desc="This content came from a partial called via a shortcode." >}}

Documenter le contrat rendu#

Chaque enregistrement de data/shortcodes.yml possède un mode de documentation. Omettez documentation_mode pour le mode live normal et rendez un appel actif dans les pages de référence bilingues. Utilisez documentation_mode: dependent avec exactement un champ preview_parent ou preview_page lorsque le shortcode dépend d’une composition parente ou de véritables données de page; les deux pages de référence doivent pointer vers cet exemple rendu avec component-relationship.

Utilisez documentation_mode: nonvisual seulement lorsque l’interface n’a aucun état rendu autonome. Rédigez alors des sections Result et Constraints en anglais, puis Résultat et Contraintes en français. Décrivez le résultat ou la transformation, les entrées lues et la limite que l’appelant doit préserver. Une maquette décorative ne constitue pas une preuve d’un contrat non visuel.

npm run lint:interfaces vérifie le mode, les deux traductions, l’appel actif ou la cible de la relation ainsi que les sections non visuelles requises.

Quand ne pas en créer#

Créez un shortcode lorsque l’alternative répète du balisage ou lorsque le contenu doit lire des données du site, par exemple definition dans le glossaire ou emoji dans la table des émojis.

N’en créez pas lorsque Markdown fournit déjà la bonne syntaxe. Les encadrés en sont l’exemple le plus net : le passage d’une forme réservée au shortcode à la syntaxe d’alerte standard > [!NOTE] permet au même texte de fonctionner dans Bear, GitHub et ce site. Un shortcode crée une petite dépendance propre au site. Utilisez-en un lorsqu’il justifie ce coût.