Hugo: Shortcodes

Article published the 29 November 2019; modified the 9 June 2021
10 minutes to read

This article has 1970 words.
RAW source of the article:

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:

File: abbr.html

1

<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

File: 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>

Call the shortcode as:

Code: shortcode

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

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

Code: shortcode

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

blockquote

Writing a basic element HTML blockquote, you need only:

File:

1

<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

File: 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>

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

File: 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>

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:

File: file.html

1

<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

File: 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>

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. But, this shortcode exists to specify width of image, and link to the raw image.

RAW source of the shortcode: img

File: img.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{{ $src := .Get "s" }}{{ $alt := .Get "a" }}{{ $ext := path.Ext $src | strings.TrimPrefix "." }}
<figure>
	<a href="/img/{{ $src }}" title="{{ $alt }}">
	<picture>
		<source srcset="/img/{{ $src }}.avif" type="image/avif">
		<source srcset="/img/{{ $src }}.webp" type="image/webp">
		<img alt="{{ $alt }}" src="/img/{{ $src }}" type="image/{{ $ext }}" width="{{ .Get "w" }}">
	</picture>
	</a>
	<figcaption>{{ $alt }}</figcaption>
</figure>

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.

kbd

This shorcode manage HTML item kbd.

RAW source of the shortcode: kbd

The shortcode is:

Code: html

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

File: 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 }}

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

File: 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 }}

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

File: 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>

The shortcode is:

Code:

{{< note id >}}
Ceci est un 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:

Code: html

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

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>

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:

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>

Examples:

Link to the manpage Packet Filter : pf(4)
Other link, about : 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:

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>

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/