Hugo Shortcodes

Article publié, le et modifié le
13 minute(s) de lecture

Cet article contient 2609 mots.
Source brute de l'article : MD

Description

Un shortcode Hugo est un fichier contenant un type précis d'éléments HTML pour pouvoir augmenter les possibilités d’Hugo.
Lors d’un appel de ce shortcode depuis un fichier MD , un traitement est fait afin de remplacer l’appel du shorcode par le traitement restitué par le shortcode lui-même.

Il est ainsi possible par ce biais d’appeler des iframes, des figures, etc… voire un fichier MD lui-même.

Les shortcodes s’enregistrent dans le répertoire layout/shortcodes/.


Pour l’instant, j’utilise le paquet tiers fournis par l'équipe OpenBSD :

  • OpenBSD : 6.6
  • Version d’Hugo : 0.53 : Hugo Static Site Generator v0.53 openbsd/amd64 BuildDate: unknown

Documentation

Mes shortcodes

Mes usages pour l’instant sont très basiques ; en soit ce que je fais au-travers de plusieurs pourraient être directement écrit dans le fichier MD au format HTML, et zou, basta…

Néanmoins, il faut avouer que pour l’inclusion d’exemples de code, surtout dans un site multilangue est franchement utile.

abbr

Gestion des abbréviations, élément abbr HTML :

Source brute vers le shortcode : abbr

Le shortcode :

Fichier : abbr.html

1
<abbr {{ .Get 1 | printf `title=%q` | safeHTMLAttr }}>{{ .Get 0 | safeHTML }}</abbr>


L’appel du shortcode est simple :

Code : shortcode

{{< abbr accronym "Meaning of Acronym" >}}

  • accronym est l’acronyme ou l’abbréviation
  • Meaning of Acronym est la signification de l’acronyme

Exemple : HTML est écrit ainsi :

Code : shortcode

{{< abbr HTML "HyperText Markup Language" >}}

anchor

La gestion des ancres dans une même page est un peu plus délicate :

Source brute vers le shortcode : anchor

Fichier : anchor.html

1
2
{{ $txt := .Get 0 | safeHTML }}{{ $name := .Get 1 | lower | safeHTML }}{{ $anchor := anchorize $name }}
<a href="{{ printf "%s" .Page.RelPermalink }}#{{ $anchor }}" title="{{ i18n "shortcodeAnchorTitle" }}{{ $name }}">{{ $txt }}</a>


L’appel du shortcode :

Code : shortcode

{{< anchor "Texte" "Cible" >}}


Exemple : Ce lien renvoie au chapitre Description, et est écrit ainsi :

Code : shortcode

{{< anchor "lien" "description" >}}

blockquote

Ahhh, la gestion des citations, autrement dit des éléments blockquote m’en a fait baver. :p

En même temps, j’ai voulu pour des histoires d’esthétiques CSS les “améliorer”.

Basiquement, il suffit :

Fichier :

1
<blockquote>{{ $file := .Get 0 | readFile | htmlUnescape | safeHTML }}{{ $file }}</blockquote>

Mon shortcode est un poil plus évolué, car le site étant multilangue, il appele le shortcode interne dédiée à la gestion multilange, le reste n'étant que de la mise en forme CSS :

Source brute vers le shortcode : blockquote

Fichier : blockquote.html

1
<div class="info-quote"><p class="text-white-50">{{ i18n "quoteTitle" }}{{ if .Get 1 }} <em>{{ .Get 1 | safeHTML }}</em>{{ end }}</p></div><div class="quote"><blockquote>{{ $name := .Get 0 }}{{ $file := urlize (print "/content/inc/" $name) | readFile | htmlUnescape | safeHTML }}{{ $file }}</blockquote></div>


L’appel du shortcode est :

Code : shortcode

{{< blockquote "blockquote-filename" lang >}}

  • blockquote-filename est le nom du fichier à appeler contenant la citation à montrer.
  • lang est le nom de la langue cible, tel en, fr, etc… - Pour ne préciser aucun langage en soit, utilisez "" - deux fois les double quotes -.

Exemple :

Citation : fr

Ceci est une citation, en français, ni plus ni moins.

Code

L’inclusion de code !

Pour pouvoir utiliser cette fonction, j’ai créé à la racine du répertoire content/ un sous répertoire nommé inc - vous pouvez très bien l’appeler autrement, à vous d’adapter lors de l’appel du shortcode - ; puis je créé mes fichiers à inclure dans ce répertoire.

Encore une fois, de manière basique, il suffit de :

Code : html

{{ $file := .Get 0 | readFile }}{{ $lang := .Get 1 }}{{ $opt := "" }}<div class="code">{{ highlight $file $lang $opt }}</div>

Mon shortcode, un poil plus évolué , du fait d'être multilangue :

Source brute vers le shortcode : code

Fichier : code.html

1
2
{{ $name := .Get 0 }}{{ $file := urlize (print "/content/inc/" $name) | readFile }}{{ $lang := .Get 1 }}{{ $opt := "" }}
<div class="info-code"><p class="text-white-50">{{ i18n "codeTitle" }}&nbsp;<em>{{ $lang }}</em></p></div><div class="code">{{ highlight $file $lang $opt }}</div>


L’appel du shortcode :

Code : shortcode

{{< code "code-filename" language >}}

  • code-filename est le nom du fichier à appeler contenant le code à montrer.
  • language est le nom du langage cible, tel sh, PHP, python, etc… - Pour ne préciser aucun langage en soit, utilisez "" - deux fois les double quotes -.

Exemple : Regardez bien, vous en avez un, juste au-dessus… lors de l’appel du premier shortcode concernant ce shortcode !

Color

Un tout petit shortcode pour gérer un bout de texte en couleur…
Néanmoins, pour cela, j’ai défini dans ma feuille de style, des types de couleurs nommées.

Source brute vers le shortcode : color

Le shortcode :

Fichier : file.html

1
<span {{ .Get 0 | printf `class=%q` | safeHTMLAttr }}>{{ .Inner }}</span>


L’appel du shortcode est simple :

Code : shortcode

{{< color "css-name" >}}text{{< /color >}}

  • css-name est le nom de la déclaration CSS
  • text est le texte à coloriser

Exemple : Ceci est un texte vert , celui qui suit est orangé , cet autre est rouge , etc…

File

L’inclusion d’un exemple de fichier est un dérivé du shortcode code , mais au lieu de produire un bloc de code précédé d’un entête présentant le code, j’appelle un entête qui restitue le nom de fichier tel que désiré.

Donc, basiquement c’est le même shortcode que pour code.

De manière plus évolué, cela donne ainsi :

Source brute vers le shortcode : file

Fichier : file.html

1
2
{{ $name := .Get 0 | safeHTML }}{{ $file := urlize (print "/content/inc/" $name) | readFile }}{{ $lang := .Get 1}}{{ $filename := .Get 2 }}{{  $opt := "linenos=table" }}
<div class="info-file"><p class="text-white-50">{{ i18n "fileTitle" }}<em>{{ $filename }}</em></p></div><div class="code">{{ highlight $file $lang $opt }}</div>


L’appel du shortcode :

Code : shortcode

{{< file "example-file" language "filename" >}}

  • /example-file est le nom du fichier à appeler contenant le contenu d’un fichier à montrer.
  • language est le nom du langage cible, tel sh, PHP, python, etc… Pour ne préciser aucun langage en soit, utilisez "" - deux fois les double quotes -.
  • filename est le nom du fichier - celui qui est affiché.

Exemple : y’a-t-il vraiment besoin encore de le prouver ? Regardez bien juste au-dessus ;)

Image

Il est vrai que Markdown a un code prévu pour l’inclusion d’image, mais j’ai crée ce shortcode pour pouvoir spécifier une taille d’image et renvoyé vers l’image source par le biais d’un élément HTML a appliqué sur l'élément HTML img.

Source brute vers le shortcode : img

Fichier : img.html

1
{{ $src := .Get "s" }}{{ $alt := .Get "a" }}<a href="/img/{{ $src }}" title="{{ $alt }}"><img src="/img/{{ $src }}" alt="{{ $alt }}" width="{{ .Get "w" }}"></a>


L’appel du shortcode :

Code : shortcode

{{< img a="alt" s="src" w="width" >}}

Les paramètres nommés sont :

  • a : l'équivalent de l’attribut alt
  • s : l'équivalent de l’attribut src
  • w : l'équivalent de l’attribut width

Exemple :

Mon Logo

Cette image représentant mon logo, ayant pour titre “Mon Logo”, a une taille de 192 px , redimensionnée à la taille de 124 pixels, et est au format PNG .

kbd

Ce shortcode est utilisé pour la gestion de l'élément HTML kbd.

Source brute vers le shortcode : kbd

Le shortcode :

Code : html

{{ $k := .Get 0 | safeHTML }}<kbd>{{ $k }}</kbd>


L’appel du shorcode :

Code : shortcode

{{< kbd key >}}

  • key est le nom de la touche clavier !

Exemple : voici le rendu de la touche A !

Lien interne

Ce shortcode a deux versions légérement différentes. J’ai commencé avec la première , puis un jour, je me suis demandé comment faire pour “injecter” aussi le nom d’une ancre ; la v2 est née !

Inside v1

Pour gérer les liens internes entre les pages de ce site, je me suis évertué à mettre en place le shortcode suivant :

Source brute vers le shortcode : inside

Fichier : inside.html

1
2
3
4
5
6
{{ $link := .Get 0 }}{{ $link := replace $link ":" "/" }}{{ $url := (print ( relLangURL $link ) "/") }}
{{ if .Get 1 }}{{ $txt := .Get 1 }}
<a class="inside" href="{{ $url }}" title="{{ i18n "lnkInsideTitle" }}{{ with .Site.GetPage $link }}{{ .Title }}{{ end }}">{{ $txt }}</a>
{{ else }}
{{ with .Site.GetPage $link }}{{ $title := .Title }}<a class="inside" href="{{ $url }}" title="{{ i18n "lnkInsideTitle" }}{{ $title }}">{{ $title }}</a>{{ end }}
{{ end }}

De même, j’ai créé une définition CSS, nommée inside, qui me permet de modifier légérement le rendu pour les liens internes.


L’appel du shortcode :

Code : shortcode

{{< inside "section:subsection:pagename" "Title" >}}

  • les noms de sections et pages sont séparés par un :
  • Le Titre peut être omis, dans ce cas-là sera affiché celui de la page appelée.

Exemples :

Inside v2

Cette version est subtilement différente :

Source brute vers le shortcode : inside2

Fichier : inside2.html

1
2
3
4
5
{{ $link := .Get "l" }}{{ $link := replace $link ":" "/" }}{{ $url := (print ( relLangURL $link ) "/") }}{{ $anchor := .Get "a" }}
{{ if .Get "t" }}{{ $txt := .Get "t" }}<a class="inside" href="{{ $url }}{{ if $anchor }}#{{ $anchor }}{{ end }}" title="{{ i18n "lnkInsideTitle" }}'{{ with .Site.GetPage $link }}{{ .Title }}{{ end }}'">{{ $txt }}</a>
{{ else }}
{{ with .Site.GetPage $link }}{{ $title := .Title }}<a class="inside" href="{{ $url }}{{ if $anchor }}#{{ $anchor }}{{ end }}" title="{{ i18n "lnkInsideTitle" }}'{{ $title }}'">{{ $title }}</a>{{ end }}
{{ end }}


L’appel du shortcode :

Code : shortcode

{{< inside2 l="section:subsection:pagename" t="title" a="anchor-name" >}}

Les paramètres nommés sont :

  • a : cible une ancre dans le document appelé ; bien-sûr, cette ancre doit exister… dans le document en question. Peut-être omise !
  • l : nom du lien interne ; les noms de sections et pages sont séparés par le symbole :
  • t : le titre. Peut être omis, dans ce cas-là sera affiché celui de la page appelée.

Exemple :

  • Là, j’appelle la page Hugo : Déploiement SFTP ; c’est son titre qui est fourni, ainsi que l’URL adéquate, mais elle pointe vers le chapitre rsync, ciblée par l’ancre correspondante.
  • Dans cet exemple, je force le titre dans l’appel de ma page Déploiement d'un site statique par Hugo mais je ne cible pas d’ancre.

Note

Les blocs d’alertes ou de notes sont des blocs de code HTML présentant un texte et mis en valeur selon un identifiant, qui est traduit selon la langue utilisée.

La valeur de cet identifiant peut être :

  • danger pour afficher une alerte de type ‘danger’ qui aura une teinte rougée
  • info pour afficher un message de type ‘information’ qui aura une teinte bleutée
  • success pour afficher un message de type ‘succès’ qui aura une teinte verte
  • tip pour afficher un message de type ‘astuce’ qui aura une teinte jaune.
  • warning pour afficher un message de type ‘attention’ qui aura une teinte orangée, jaunâtre.

Bien-sûr, ces teintes dépendent des déclarations CSS.

Le shortcode en lui-même :

Source brute vers le shortcode : note

Fichier : note.html

1
2
{{ $class := .Get 0 }}{{ $wrd := T (printf "alert-%s" $class) }}
<div class="info-tab {{ $class }}-icon">{{ $wrd }}</div><div class="alert alert-{{ $class }}" role="alert">{{ .Inner | markdownify }}</div>


L’appel du shortcode est :

Code : 

{{< note id >}}
Ceci est un message
{{< /note >}}


Exemples :

Danger
Cet exemple embarque le code MD pour mettre en gras le mot ‘ATTENTION’.

Info
Succès
Astuce
Attention

Tag

Ce shortcode n’existe pas pour gérer les tags générés par Hugo, mais pour gérer l’URL d’un tag au sein d’une page Markdown. Le shortcode va générer un élément a HTML adéquat. Il tient compte de la gestion multilangue du site.

Au sein de la page Markdown, j’intégre un mot qui se veut être un renvoi vers la page tag ad hoc.

Côté CSS, j’ai défini l’attribut ::after sur la définition .tag pour ajouter par la CSS l’information (tag) précédé du terme en question. Ce qui permet visuellement de le différencier des autres liens.

Source brute vers le shortcode : tag

Le shortcode :

Code : html

{{ $txt := .Get 0 }}{{ $href := "/" | relLangURL}}{{ $href := (printf "%s%s%s" $href "/tags/" $txt) | urlize }}<a class="tag" href="{{ $href }}">{{ $txt }}</a>


L’appel du shortcode :

Code : shortcode

{{< tag tag-name >}}


Exemple : le mot Hugo est un lien vers l’URL des articles contenant le tag “Hugo”.

Autres shortcodes

GoHugo

Pour faire un lien vers la documentation officielle d’Hugo, je me suis amusé à écrire ce shortcode :

Code : shortcode

{{< gohugo n="pagename" s="section" a="anchor-name" >}}

  • n est le nom de la page dans la documentation du site Gohugo.io
  • s est le nom de la section dans la documentation du site Gohugo.io
  • a est le nom de l’ancre à cibler dans la page

Source brute vers le shortcode : gohugo

Le shortcode est :

Code : html

{{ $section := .Get "s" }}{{ $name := .Get "n" }}{{ $anchor := .Get "a" }}<a href="https://gohugo.io/{{ $section }}/{{ $name }}/{{ if $anchor }}#{{ $anchor}}{{ end }}" title="{{ i18n "shortcodeGoHugoTitle" }}{{ humanize $section }} &gt; {{ humanize $name }}">{{ i18n "shortcodeGoHugoDocTitle" }}{{ humanize $section }} &gt; {{ humanize $name }}</a>


Exemple: Le lien vers la page Hugo Documentation : Content management > Shortcodes Hugo.
voici le shortcode correspondant :

Code : shortcode

{{< gohugo n="shortcodes" s="content-management" >}}

Manpage

Utilisant souvent des renvois vers les manpages officiels d’OpenBSD, je me suis crée le shortcode suivant :

Code : shortcode

{{< man title digit >}}

  • Si un chiffre (digit) est fourni, le shortcode le restituera à la fois, dans l’URL reconstituée, que dans le texte affiché. Dans l’URL, ce sera de type txt.digit ; le texte affiché aura le chiffre entouré des parenthèses, tel que txt(digit).

Source brute vers le shortcode : man

Le shortcode est :

Code : html

{{ $txt := .Get 0 }}{{ $nb := .Get 1}}
<a class="man" href="https://man.openbsd.org/{{ $txt }}{{ if $nb }}{{ print "." $nb }}{{ end }}" title="{{ i18n "manpageTitle" }}{{ $txt }}">{{ $txt }}{{ if $nb }}{{ print "(" $nb ")" }}{{ end }}</a>


Exemples :

Wikipedia

De même pour l’encyclopédie Wikipédia, le shortcode créé est le suivant :

Code : shortcode

{{< wp "url-article" >}}


Source brute vers le shortcode : wp

Le shortcode est :

Code : html

{{ $txt := .Get 0 }}{{ $title := print (i18n "wpTitleArticle") $txt }}<a href="https://{{ .Site.Language.Lang }}.wikipedia.org/wiki/{{ $txt }}" title="{{ $title }}">Wikipedia :: {{ $txt }}</a>


Exemples :

Ailleurs

Pour finir, n’hésitez pas à vous amuser avec les shortcodes, faites-vous aider sur le forum de la communauté, malheureusement pour nous francoph(on|il)es, en anglais.