Hugo: Shortcodes

Article published the ; modified the
10 minute(s) to read

This article has 1930 words.
RAW source of the article: MD

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

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
{{ $src := .Get "s" }}{{ $alt := .Get "a" }}<a href="/img/{{ $src }}" title="{{ $alt }}"><img src="/img/{{ $src }}" alt="{{ $alt }}" width="{{ .Get "w" }}"></a>


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!

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:

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
This example includes MD code to strong the word ‘ATTENTION’.

Info
Success
Tip
Warning

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:

Somewhere

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