Hugo: Shortcodes

Article published the29 November 2019 ; modified the7 March 2024
10 minutes to read

This article has 2080 words.
RAW source of the article:
Commit version: edea221

Description

As you see on Hugo’s page shortcodes, a shortcode is a simple snippet inside a content file that Hugo will render using a predefined template.

Some times, you need to include/add raw HTML into the MD content. The shortcode add correctly this. By this way, you can include too MD syntax.

Put your shortcodes into layout/shortcodes/.

Actually, I use the official third package providen by the team OpenBSD:

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

Documentation

official : Hugo Documentation: Content management > Shortcodes

My shortcodes

abbr

To manage element HTML abbr

RAW source of the shortcode: abbr

The shortcode:

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

Call the shortcode as:

Code: shortcode


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

Example: HTML is written as:

Code: shortcode


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

anchor

To manage the anchor into one page is a little complex:

RAW source of the shortcode: anchor

{{ $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>

Call the shortcode as:

Code: shortcode


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

Example: this link refers to the section Description; his writing is:

Code: shortcode


{{< anchor "link" "description" >}}

blockquote

Writing a basic element HTML blockquote, you need only:

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

But, my shorcode is more evolved, because as you see, this site is multilanguage. Also:

RAW source of the shortcode: blockquote

<div class="info-quote"><p class="text-white-50">{{ T "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>

Call the shortcode as:

Code: shortcode


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

blockquote-filename: the file to call where the blockquote is written
lang: the lang, i.e en, fr, etc. - To avoid specifying an code, use "".

Example:

Quotes: fr

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

Code

To include some example code, I created into content/ folder a directory named inc. You can named as you want; it’s up to you!

And after, create needed files, and call them as /content/folder_name/file_name.

By default:

Code: html


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

For my needs, my shortcode is “a little more” advanced:

RAW source of the shortcode: code

{{ $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>

Call the shortcode as:

Code: shortcode


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

code-filename: the file to call
language: the language, i.e sh, PHP, python, etc. To avoid specifying an code, use "".

Example: Look, you have one just above it!

Color

A very small shortcode to add color on text.

Into my CSS , I had some definitions with named colors.

RAW source of the shortcode: color

The shortcode:

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

Call the shortcode as:

Code: shortcode


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

css-name: the CSS name
text: the text

Example: This is green text , or orange , and this other is red , etc…

File

To include a file content example, I fork the shortcode code . It’s quasy-same code.

But, for my need, I wrote an advanced as:

RAW source of the shortcode: file

{{ $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>

Call the shortcode as:

Code: shortcode


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

/example-file: file to call
language: language, i.e. sh, PHP, python, etc… To avoid specifying an code, use "".
filename: filename to display ;)

Example: Look above to see!

Image

Yes, I known Markdown had his code to include basically image.

PNG/JPG/Tiff

This shortcode exists to specify width of image, and link to the raw image.

RAW source of the shortcode: img

 1{{/* runner for assets/image */}}
 2{{- $src := resources.Get (printf "%s%s" "/images/" (.Get "s")) -}}{{- $alt := .Get "a" | safeHTML -}}{{- $width := printf "%s" (.Get "w") -}}
 3{{- $img := $src -}}
 4{{- with $width -}}{{- $img = $src.Resize (printf "%sx" $width) -}}{{- end -}}
 5{{- with $img -}}
 6<figure>
 7	<a href="{{ $src.RelPermalink }}" title="{{ $alt }}">
 8	<picture>
 9		<!-- <source srcset="/img/.avif" type="image/avif"> -->
10        {{- with .Resize (printf "%dx%d webp" .Width .Height) }}
11		<source srcset="{{ .RelPermalink }}" type="image/webp">
12        {{ end }}
13		<img alt="{{ $alt }}" loading="lazy" src="{{ .RelPermalink }}" type="{{ .MediaType }}" height="{{ .Height }}" width="{{ .Width }}">
14	</picture>
15	</a>
16	<figcaption>{{ $alt }}</figcaption>
17</figure>
18{{- end -}}

Call the shortcode as:

Code: shortcode


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

The named parameters are:

a: equivalent for attribute alt
s: equivalent for attribute src
w: equivalent for attribute width

Example:

My Logo

This image is my logo, named “My Logo”, with an original width at 192 px , resized at 124 px, into PNG format.

SVG

About the SVG picture, I manage them like as:

RAW source of the shortcode: figure-svg

 1{{/* runner for assets/svg */}}
 2{{- $class := .Get "class" -}}{{- $src := resources.Get (printf "%s%s" "/svg/" (.Get "src")) -}}{{ $title := .Get "title" }}
 3{{ with $src }}
 4<figure class="{{ if $class }}{{ $class }}{{ end }}">
 5    <a href="{{ .RelPermalink }}" title="{{ $title }}">
 6    {{ .Content | safeHTML }}
 7    </a>
 8    {{ if $title }}<figcaption aria-hidden="true" class="hidden" hidden>{{ $title }}</figcaption>{{ end }}
 9</figure>
10{{ end }}

Call the shortcode:

Code: shortcode


{{< figure-svg class="class-name" src="image.svg" title="the title" >}}

Example :

kbd

This shorcode manage HTML item kbd.

RAW source of the shortcode: kbd

The shortcode is:

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

Call shortcode as:

Code: shortcode


{{< kbd key >}}

key: the key name into the keyboard!

Example : this is for the s key!

Inside link

This shortcode, now, had two versions. I started with the first , and one day, I wonder how add anchor too; the v2 was born!

Inside v1

To manage inside link between pages of this site, I wrote this shortcode:

RAW source of the shortcode: inside

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

And, I created into my CSS, a named inside definition.

Call the shortcode as:

Code: shortcode


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

sections and pages names are separated by the symbol :
the title can be avoid. In this case, it will display the title of called page.

Examples:

In this exemple, I call the page Hugo: Deploy SFTP ; this is its title that is displayed.
With this other example, I override the title when I call the same page Static deploy with Hugo

Inside v2

This version is subtle different:

RAW source of the shortcode: inside2

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

Call the shortcode as:

Code: shortcode


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

The named parameters are:

a: target an anchor into called page. this anchor need to exists into the page. May be omitted!
l: name of internal link; sections and pages names are separated by the symbol :.
t: the title. May be omitted. In this case, it will display tye title of the called page.

Example:

Here, I call the page Hugo: Deploy SFTP. Her title is displayed, but it links to the section named rsync, targeted anchor.
And this example, I override the title as Static deploy with Hugo but I not wrote anchor param.

Note

The blocs of alert or note are HTML blocs to display a text, with an identifiant, translated segun the used lang.

The possible values of this identifiant may be:

danger: to display an alert ‘danger’, with a red background.
info: to display an informational note, with a blue background.
success: to display a success message, with a green background.
tip: to display a tip note, with a yellow background.
warning: to display a warning message/alert, with an amber background.

And, all thoses background colors alert-$id are written on CSS file.

The shortcode:

RAW source of the shortcode: note

{{ $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 | .Page.RenderString }}</div>

The shortcode is:

Code: shortcode


{{< note id >}}
This is your message
{{< /note >}}

Examples:

Danger

ATTENTION: this message display a risk or danger for you!

This example includes MD code to strong the word ‘ATTENTION’.

Info

A little information. Keep this in your mind! :D

Success

You succeeded the test! Be happy.

Tip

This is a tip. Yeah, man, interesting!

Warning

Please, be careful at the message: it seems a malfunction exists. See more attentive!

Tag

This shortcode not exists to manage Hugo tags, but to manage tag into MD file.

Into CSS, I defined attribute .tag::after to display (tag).

RAW source of the shortcode: tag

The shortcode:

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

Call the shortcode as:

Code: shortcode


{{< tag tag-name >}}

Example: This word Hugo is a link to the tag page with “Hugo” name.

Others shortcodes

GoHugo

Just to link to official documentation Hugo, I wrote this shortcode:

Code: shortcode


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

RAW source of the shortcode: gohugo

The shortcode:

{{ $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>

Example: Link to Hugo Documentation: Content management > Shortcodes Hugo page with:

Code: shortcode


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

Manpage

As I use many times links to official manpage OpenBSD, I wrote this shortcode:

Code: shortcode


{{< man title digit >}}

If a digit is written, the shortcode build the URL as title.digit and the text as txt(digit).

RAW source of the shortcode: man

The shortcode:

{{ $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>

Examples:

Link to the manpage Packet Filter: pf(4)
Other link: httpd(8)
And, the last but not the least: man

Wikipedia

Egual, for the Wikipedia, the shortcode is:

Code: shortcode


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

RAW source of the shortcode: wp

The shortcode:

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

Examples:

This is an article to promote OpenBSD: OpenBSD ^WP
This other is for Debian: Debian ^WP
And, a third more complex: Firewall_(computing) ^WP

Somewhere

Finally, do not hesitate to have fun with the shortcodes; get help on the commmunity forum.

https://after-dark.habd.as/shortcode/