GESTION DE CONTENU

Shortcodes

C’est Quoi un Shortcode

Hugo adore le Markdown en raison de son format de contenu simple, mais il arrive parfois que Markdown échoue. Souvent, les auteurs de contenu sont forcés d’ajouter du HTML brut (par exemple, la vidéo <iframes>) au contenu Markdown. Nous pensons que cela va à l’encontre de la belle promesse de simplicité de la syntaxe de Markdown.

Hugo a créé les shortcodes pour contourner ces limitations.

Un shortcode est un extrait simple dans un fichier de contenu que Hugo rendra à l’aide d’un modèle prédéfini. Notez que les codes courts ne fonctionneront pas dans les fichiers de modèle. Si vous avez besoin du type de fonctionnalité déroulante fournie par les shortcodes, mais dans un modèle, vous ferez probablement à la place un modèle partiel.

En plus d’un Markdown plus propre, ces codes courts peuvent être mis à jour à tout moment pour renvoyer de nouvelles classes, techniques ou standards. Au stade de génération du site, les codes courts de Hugo se fusionneront facilement dans vos modifications. Vous évitez une opération de rechercher/ remplacer éventuellement compliquée.

Utiliser les Shortcodes

Dans vos fichiers de contenu, un shortcode peut être appelé en appelant {{% nomshortcode parametres %}}. Les paramètres de shortcode sont délimités par un espace et les paramètres avec des espaces internes peuvent être cités.

Le premier mot dans la déclaration shortcode est toujours le nom du shortcode. Les paramètres suivent le nom. Selon la façon dont le code court est défini, les paramètres peuvent être nommés, positionnels ou les deux, bien que vous ne puissiez pas mélanger les types de paramètres en un seul appel. Le format pour les modèles de paramètres nommés est celui de HTML avec le format nom="valeur".

Certains codes courts utilisent ou nécessitent la fermeture de codes courts. Encore une fois comme en HTML, les codes abrégés d’ouverture et de fermeture correspondent (nom uniquement) à la déclaration de clôture, qui est précédée d’une barre oblique.

Voici deux exemples de codes courts couplés :

{{% mdshortcode %}}Stuff to `process` in the *center*.{{% /mdshortcode %}}

{{< highlight go >}} A bunch of code here {{< /highlight >}}

Les exemples ci-dessus utilisent deux délimiteurs différents, la différence étant le caractère %' dans le premier et les caractères<>` dans le second.

Shortcodes avec Markdown

Le caractère % indique que le contenu interne du shortcode — appelé dans le modèle shortcode avec la variable .Inner— nécessite un traitement ultérieur par le processeur de rendu de la page (c.-à-d. via Blackfriday). Dans l’exemple suivant, Blackfriday convertirait **World** en <strong>World</ strong> :

{{% myshortcode %}}Hello **World!**{{% /myshortcode %}}

Shortcodes Sans Markdown

Le caractère < indique que le contenu interne du shortcode ne nécessite pas plus de rendu. Souvent, les codes courts sans markdown incluent du HTML interne :

{{< myshortcode >}}<p>Hello <strong>World!</strong></p>{{< /myshortcode >}}

Shortcodes Imbriqués

Vous pouvez appeler des codes courts dans d’autres shortcodes en créant vos propres modèles qui utilisent la variable .Parent. .Parent vous permet de vérifier le contexte dans lequel le code court est appelé. Voir Modèles de shortcode.

Utiliser les Shortcodes Intégrés de Hugo

Hugo est livré avec un ensemble de codes courts prédéfinis qui représentent un usage très courant. Ces codes courts sont fournis pour la commodité de l’auteur et pour maintenir votre contenu markdown propre.

figure

figure est une extension de la syntaxe image en markdown, qui ne fournit pas de raccourci pour l’élément plus sémantique <figure> du HTML5.

Le shortcode figure peut utiliser les paramètres nommés suivants :

  • src
  • link
  • title
  • caption
  • class
  • attr (i.e., attribution)
  • attrlink
  • alt

Exemple Input figure

figure-input-example.md
{{< figure src="/media/spf13.jpg" title="Steve Francia" >}}

Exemple Output figure

figure-output-example.html
<figure>
  <img src="/media/spf13.jpg"  />
  <figcaption>
      <h4>Steve Francia</h4>
  </figcaption>
</figure>

gist

Les blogueurs veulent souvent inclure des gists GitHub au moment d’écrire des posts. Supposons que nous voulions utiliser le gist à l’url qui suit :

https://gist.github.com/spf13/7896402

Nous pouvons intégrer le gist dans notre contenu via le nom d’utilisateur et l’ID gist extraite de l’URL :

{{< gist spf13 7896402 >}}

Exemple Input gist

Si le gist contient plusieurs fichiers et que vous souhaitez citer un seul d’entre eux, vous pouvez passer le nom de fichier (cité) en tant que troisième argument facultatif :

gist-input.md
{{< gist spf13 7896402 "img.html" >}}

Exemple Output gist

gist-output.html
<script src="//gist.github.com/spf13/7896402.js"></script>

Exemple Affichage gist

Pour démontrer l’efficacité remarquable de la fonctionnalité shortcode de Hugo, nous avons intégré l’exemple gist spf13 dans cette page. Ce qui suit simule l’expérience pour les visiteurs de votre site. Naturellement, l’affichage final dépend de vos feuilles de style et des balises environnantes.

highlight

Ce code court convertira le code source fourni en HTML mettant la syntaxe en surbrillance. Pour en savoir plus, regardez mise en surbrillance. highlight prend exactement un paramètre language requis et nécessite un shortcode de fermeture.

Exemple Input highlight

content/tutorials/learn-html.md
{{< highlight html >}}
<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Data.Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>
{{< /highlight >}}

Exemple Output highlight

Cet exemple de shortcode highlight au-dessus produirait le HTML suivant au moment où le site est produit :

tutorials/learn-html/index.html
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
  <span style="color: #f92672">&lt;div&gt;</span>
   <span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
    {{ range .Data.Pages }}
        {{ .Render &quot;summary&quot;}}
    {{ end }}
  <span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>

instagram

Si vous souhaitez intégrer une photo provenant d’Instagram, vous n’avez besoin que de l’ID de la photo. Vous pouvez retrouver l’ID de photo Instagram à partir de l’URL :

https://www.instagram.com/p/BWNjjyYFxVx/

Exemple Input instagram

instagram-input.md
{{< instagram BWNjjyYFxVx >}}

Vous avez aussi l’option de cacher la légende :

instagram-input-hide-caption.md
{{< instagram BWNjjyYFxVx hidecaption >}}

Exemple Output instagram

En ajoutant l’exemple précédent hidecaption, le HTML suivant sera ajouté à votre marquage de rendu de site web :

instagram-hide-caption-output.html
<blockquote class="instagram-media" data-instgrm-version="7" style=" background:#FFF; border:0; border-radius:3px; box-shadow:0 0 1px 0 rgba(0,0,0,0.5),0 1px 10px 0 rgba(0,0,0,0.15); margin: 1px; max-width:658px; padding:0; width:99.375%; width:-webkit-calc(100% - 2px); width:calc(100% - 2px);"><div style="padding:8px;"> <div style=" background:#F8F8F8; line-height:0; margin-top:40px; padding:33.251231527093594% 0; text-align:center; width:100%;"> <div style=" background:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAsCAMAAAApWqozAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAMUExURczMzPf399fX1+bm5mzY9AMAAADiSURBVDjLvZXbEsMgCES5/P8/t9FuRVCRmU73JWlzosgSIIZURCjo/ad+EQJJB4Hv8BFt+IDpQoCx1wjOSBFhh2XssxEIYn3ulI/6MNReE07UIWJEv8UEOWDS88LY97kqyTliJKKtuYBbruAyVh5wOHiXmpi5we58Ek028czwyuQdLKPG1Bkb4NnM+VeAnfHqn1k4+GPT6uGQcvu2h2OVuIf/gWUFyy8OWEpdyZSa3aVCqpVoVvzZZ2VTnn2wU8qzVjDDetO90GSy9mVLqtgYSy231MxrY6I2gGqjrTY0L8fxCxfCBbhWrsYYAAAAAElFTkSuQmCC); display:block; height:44px; margin:0 auto -44px; position:relative; top:-22px; width:44px;"></div></div><p style=" color:#c9c8cd; font-family:Arial,sans-serif; font-size:14px; line-height:17px; margin-bottom:0; margin-top:8px; overflow:hidden; padding:8px 0 7px; text-align:center; text-overflow:ellipsis; white-space:nowrap;"><a href="https://www.instagram.com/p/BWNjjyYFxVx/" style=" color:#c9c8cd; font-family:Arial,sans-serif; font-size:14px; font-style:normal; font-weight:normal; line-height:17px; text-decoration:none;" target="_blank">A post shared by Bjørn Erik Pedersen (@bepsays)</a> on <time style=" font-family:Arial,sans-serif; font-size:14px; line-height:17px;" datetime="2017-07-06T16:27:46+00:00">Jul 6, 2017 at 9:27am PDT</time></p></div></blockquote>
<script async defer src="//platform.instagram.com/en_US/embeds.js"></script>

Exemple Affichage instagram

En utilisant l’exemple précédent instagram avec l’exemple hidecaption ci-dessus, ce qui suit simule l’expérience affichée pour les visiteurs de votre site. Naturellement, l’affichage final dépend de vos feuilles de style et des balises environnantes.

ref and relref

Ces shortcodes recherchent les pages par leur chemin relatif (par ex., blog/post.md) ou leur nom logique (post.md) et renvoient le permalien (ref) ou le permalien relatif (relref) pour la page trouvée.

ref et relref permettent également de créer des liens fragmentaires qui fonctionnent pour les liens d’en-tête générés par Hugo.

ref et relref prennent exactement un paramètre requis de reference, citée et en position 0.

Exemple Input ref and relref

[Neat]({{< ref "blog/neat.md" >}})
[Who]({{< relref "about.md#who" >}})

Exemple Output ref et relref

En supposant que les pretty URLs standards d’Hugo soient activées :

<a href="/blog/neat">Neat</a>
<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>

speakerdeck

Pour embarquer les slides provenant de Speaker Deck, cliquez sur “< /> Embed” (sous Share tout à droite du modèle sur Speaker Deck) et copiez l’URL :

<script async class="speakerdeck-embed" data-id="4e8126e72d853c0060001f97" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>

Exemple Input speakerdeck

Extrayez la valeur du champ data-id et passez-la dans le shortcode :

speakerdeck-example-input.md
{{< speakerdeck 4e8126e72d853c0060001f97 >}}

Exemple Output speakerdeck

speakerdeck-example-input.md
<script async class='speakerdeck-embed' data-id='4e8126e72d853c0060001f97' data-ratio='1.33333333333333' src='//speakerdeck.com/assets/embed.js'></script>

Exemple Affichage speakerdeck

Pour l’exemple précédent speakerdeck, ce qui suit simule l’expérience affichée pour les visiteurs de votre site. Naturellement, l’affichage final dépend de vos feuilles de style et des balises environnantes.

tweet

Vous souhaitez inclure un tweet unique dans votre publication de blog ? Tout ce dont vous avez besoin c’est l’URL du tweet :

https://twitter.com/spf13/status/877500564405444608

Exemple Input tweet

Passez l’ID du tweet à partir de l’URL comme paramètre pour le shortcode tweet :

example-tweet-input.md
{{< tweet 877500564405444608 >}}

Exemple Output tweet

En utilisant l’exemple du tweet précédent, le HTML suivant sera ajouté au marquage de votre site web :

example-tweet-output.html
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Hugo 0.24 Released: Big archetype update + <a href="https://twitter.com/Netlify">@Netlify</a> _redirects etc. file support<a href="https://t.co/X94FmYDEZJ">https://t.co/X94FmYDEZJ</a> <a href="https://twitter.com/hashtag/gohugo?src=hash">#gohugo</a> <a href="https://twitter.com/hashtag/golang?src=hash">#golang</a> <a href="https://twitter.com/spf13">@spf13</a> <a href="https://twitter.com/bepsays">@bepsays</a></p>&mdash; GoHugo.io (@GoHugoIO) <a href="https://twitter.com/GoHugoIO/status/877500564405444608">June 21, 2017</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

Exemple Affichage tweet

En utilisant l’exemple du tweet précédent, ce qui suit simule l’expérience affichée pour les visiteurs de votre site web. Naturellement, l’affichage final dépend de vos feuilles de tyles et du marquage environnant.

vimeo

Ajouter une vidéo à partir de Vimeo est équivalent au shortcode YouTube vu au-dessus.

https://vimeo.com/channels/staffpicks/146022717

Exemple Input vimeo

Extrayer l’ID à partir de l’URL de la vidéo et passer la dans le shortcode vimeo :

example-vimeo-input.md
{{< vimeo 146022717 >}}

Exemple Output vimeo

En utilisant l’exemple vimeo précédent, le HTML suivant sera ajouté au marquage rendu de votre site :

example-vimeo-output.html

<div style="position: relative; padding-bottom: 56.25%; padding-top: 30px; height: 0; overflow: hidden;">
  <iframe src="//player.vimeo.com/video/146022717" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
 </div>

Exemple Affichage vimeo

En utilisant l’exemple vimeo précédent, ce qui suit simule l’expérience affichée pour les visiteurs de votre site web. Naturellement, l’affichage final dépend de vos feuilles de tyles et du marquage environnant.

youtube

Le shortcode youtube intègre un lecteur vidéo responsive pour les vidéos YouTube. Seul l’ID de la vidéo est requis, par exemple :

https://www.youtube.com/watch?v=w7Ft2ymGmfc

Exemple Input youtube

Copiez l’ID vidéo YouTube qui suit v= dans l’URL de la vidéo et passez la dans le shortcode youtube :

example-youtube-input.md
{{< youtube w7Ft2ymGmfc >}}

En outre, vous pouvez lancer automatiquement la lecture de la vidéo incorporée en définissant le paramètre autoplay sur true. N’oubliez pas que vous ne pouvez pas mélanger un paramètre nommé sans nom, vous devez donc attribuer l’identifiant vidéo non nommé au paramètre id :

example-youtube-input-with-autoplay.md
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}

Exemple Output youtube

En utilisant l’exemple youtube précédent, le HTML suivant sera ajouté au marquage rendu de votre site :

example-youtube-output.html

<div style="position: relative; padding-bottom: 56.25%; padding-top: 30px; height: 0; overflow: hidden;">
  <iframe src="//www.youtube.com/embed/w7Ft2ymGmfc?autoplay=1" 
  style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" allowfullscreen frameborder="0"></iframe>
</div>

Exemple Affichage youtube

En utilisant l’exemple youtube précédent (sans autoplay="true"), ce qui suit simule l’expérience affichée pour les visiteurs de votre site web. Naturellement, l’affichage final dépend de vos feuilles de tyles et du marquage environnant. La vidéo est aussi incluse dans le Quick Start de la documentation Hugo.

Créer des Shortcodes Personnalisés

Pour en savoir plus sur la création de shortcodes personnalisés, regardez la documentation du modèle de shortcode.

La page “Shortcodes” a été mise à jour le
Améliorez cette page