---
date: 2019-11-29T15:29:59+01:00
description: "My different Hugo shortcodes's presentation"
draft: false
tags: ["Hugo", "Shortcode"]
title: "Hugo: Shortcodes"
translationKey: "hugo-shortcodes"
---

## Description

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

Some times, you need to include/add raw {{< abbr HTML "HyperText Markup Language" >}} 
into the {{< abbr MD "MarkDown" >}} 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 : {{< gohugo n="shortcodes" s="content-management" >}}

## My shortcodes

### abbr

* To manage element HTML `abbr`

{{< raw abbr >}}
The shortcode:
```html
<abbr {{ .Get 1 | printf `title=%q` | safeHTMLAttr }}>{{ .Get 0 | safeHTML }}</abbr>
```

----

Call the shortcode as:
{{< code-hl shortcode >}}
{{</* abbr accronym "Meaning of Acronym" */>}}
{{</code-hl>}}

----

Example: {{< abbr HTML "HyperText Markup Language" >}} is written as:
{{< code-hl shortcode >}}
{{</* abbr HTML "HyperText Markup Language" */>}}
{{</code-hl>}}

### anchor

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

{{< raw anchor >}}
```html
{{ $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: <br>
{{< code-hl shortcode >}}
{{</* anchor "Texte" "Cible" */>}}
{{</code-hl>}}

----

Example: this {{< anchor "link" "description" >}} refers to the section 
Description; his writing is: <br>
{{< code-hl shortcode >}}
{{</* anchor "link" "description" */>}}
{{</code-hl>}}

### blockquote

Writing a basic element HTML `blockquote`, you need only:
```html
<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 blockquote >}}
```html
<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: <br>
{{< code-hl shortcode >}}
{{</* blockquote "blockquote-filename" lang */>}}
{{</code-hl>}}

* `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:
{{< blockquote "web-hugo-shortcode-example-blockquote" fr >}}

### 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-hl html >}}
{{ $file := .Get 0 | readFile }}{{ $lang := .Get 1 }}{{ $opt := "" }}<div class="code">{{ highlight $file $lang $opt }}</div>
{{</code-hl>}}

For my needs, my shortcode is "a little more" advanced:

{{< raw code >}}
```html
{{ $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-hl shortcode >}}
{{</* code "code-filename" language */>}}
{{</code-hl>}}

* `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 {{< abbr CSS "Cascaded Style Sheet" >}}, I had some definitions with named colors.

{{< raw color >}}
The shortcode:
```html
<span {{ .Get 0 | printf `class=%q` | safeHTMLAttr }}>{{ .Inner }}</span>
```

----

Call the shortcode as:
{{< code-hl shortcode >}}
{{</* color "css-name" >}}text{{< /color */>}}
{{</code-hl>}}

* `css-name`: the CSS name
* `text`: the text

----

Example: This is {{< color "dark-green" >}}green text{{< /color >}}, or {{< color "orange" >}}orange{{< /color >}}, and this other is {{< color red >}}red{{< /color >}}, etc…

### File

To include a file content example, I fork the shortcode {{< anchor code code >}}. It's quasy-same code.

But, for my need, I wrote an advanced as:
{{< raw file >}}
```html
{{ $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: <br>
{{< code-hl shortcode >}}
{{</* file "example-file" language "filename" */>}}
{{</code-hl>}}

* `/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 img >}}
```html {linenos=inline}
{{/* runner for assets/image */}}
{{- $src := resources.Get (printf "%s%s" "/images/" (.Get "s")) -}}{{- $alt := .Get "a" | safeHTML -}}{{- $width := printf "%s" (.Get "w") -}}
{{- $img := $src -}}
{{- with $width -}}{{- $img = $src.Resize (printf "%sx" $width) -}}{{- end -}}
{{- with $img -}}
<figure>
	<a href="{{ $src.RelPermalink }}" title="{{ $alt }}">
	<picture>
		<!-- <source srcset="/img/.avif" type="image/avif"> -->
        {{- with .Resize (printf "%dx%d webp" .Width .Height) }}
		<source srcset="{{ .RelPermalink }}" type="image/webp">
        {{ end }}
		<img alt="{{ $alt }}" loading="lazy" src="{{ .RelPermalink }}" type="{{ .MediaType }}" height="{{ .Height }}" width="{{ .Width }}">
	</picture>
	</a>
	<figcaption>{{ $alt }}</figcaption>
</figure>
{{- end -}}
```

----

Call the shortcode as:
{{< code-hl shortcode >}}
{{</* img a="alt" s="src" w="width" */>}}
{{</code-hl>}}

The named parameters are:

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

----

Example:

{{< img a="My Logo" s="Logo_full_192px.png" w="124" >}}

This image is my logo, named "My Logo", with an original width at 192 
{{< abbr px "pixels" >}}, resized at 124 px, into 
{{< abbr PNG "Portable Network Graphics" >}} format.

#### SVG

About the SVG picture, I manage them like as:

{{< raw figure-svg >}}
```html {linenos=inline}
{{/* runner for assets/svg */}}
{{- $class := .Get "class" -}}{{- $src := resources.Get (printf "%s%s" "/svg/" (.Get "src")) -}}{{ $title := .Get "title" }}
{{ with $src }}
<figure class="{{ if $class }}{{ $class }}{{ end }}">
    <a href="{{ .RelPermalink }}" title="{{ $title }}">
    {{ .Content | safeHTML }}
    </a>
    {{ if $title }}<figcaption aria-hidden="true" class="hidden" hidden>{{ $title }}</figcaption>{{ end }}
</figure>
{{ end }}
```

---

Call the shortcode:
{{< code-hl shortcode >}}
{{</* figure-svg class="class-name" src="image.svg" title="the title" */>}}
{{</code-hl>}}

---

Example :
{{< figure-svg class="" src="Logo_final.svg" title="My Logo" >}}

---

### kbd

This shorcode manage HTML item `kbd`.

{{< raw kbd >}}
The shortcode is:
```html
{{ $k := .Get 0 | safeHTML }}<kbd>{{ $k }}</kbd>
```

----

Call shortcode as:
{{< code-hl shortcode >}}
{{</* kbd key */>}}
{{</code-hl>}}

* `key`: the key name into the keyboard!

----

Example : this is for the  {{< kbd s >}} key!

### Inside link

This shortcode, now, had two versions. I started with 
{{< anchor "the first" "inside-v1" >}}, and one day, I wonder how add 
anchor too; {{< anchor "the v2" "inside-v2" >}} was born!

#### Inside v1

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

{{< raw inside >}}
```html {linenos=inline}
{{ $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-hl shortcode >}}
{{</* inside "section:subsection:pagename" "Title" */>}}
{{</code-hl>}}

* 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 {{< inside "web:hugo:hugo-deploy" >}}; this is its title that is displayed.
* With this other example, I override the title when I call the same page {{< inside "web:hugo:hugo-deploy" "Static deploy with Hugo" >}}

#### Inside v2

This version is subtle different:

{{< raw inside2 >}}
```html {linenos=inline}
{{ $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-hl shortcode >}}
{{</* inside2 l="section:subsection:pagename" t="title" a="anchor-name" */>}}
{{</code-hl>}}

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 {{< inside2 l="web:hugo:hugo-deploy" a="rsync" >}}. Her title is displayed, but it links to the section named **rsync**, targeted anchor.
* And this example, I override the title as {{< inside2 l="web:hugo:hugo-deploy" t="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 note >}}
```html
{{ $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-hl shortcode >}}
{{</* note id */>}}
This is your message
{{</* /note */>}}
{{</code-hl>}}

----

Examples:

{{< note danger >}}
**ATTENTION**: this message display a risk or danger for you!
{{< /note >}}
*This example includes MD code to strong the word 'ATTENTION'.*

{{< note info >}}
A little **information**. Keep this in your mind! :D
{{< /note >}}

{{< note success >}}
You succeeded the test! Be happy.
{{< /note >}}

{{< note tip >}}
This is a tip. Yeah, man, interesting!
{{< /note >}}

{{< note warning >}}
Please, be careful at the message: it seems a malfunction exists. See more attentive!
{{< /note >}}

### 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 tag >}}
The shortcode:
```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-hl shortcode >}}
{{</* tag tag-name */>}}
{{</code-hl>}}

----

Example: <br>
This word {{< tag 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-hl shortcode >}}
{{</* gohugo n="pagename" s="section" a="anchor-name" */>}}
{{</code-hl>}}

----

{{< raw gohugo >}}
The shortcode:
```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 {{< gohugo n="shortcodes" s="content-management" >}} 
 Hugo page with:
{{< code-hl shortcode >}}
{{</* gohugo n="shortcodes" s="content-management" */>}}
{{</code-hl>}}

### Manpage

As I use many times links to official manpage OpenBSD, I wrote this shortcode:
{{< code-hl shortcode >}}
{{</* man title digit */>}}
{{</code-hl>}}

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

----

{{< raw man >}}
The shortcode:
```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**: {{< man pf 4 >}}
* Other link: {{< man httpd 8 >}}
* And, the last but not the least: {{< man man >}}

### Wikipedia

Egual, for the Wikipedia, the shortcode is:
{{< code-hl shortcode >}}
{{</* wp "url-article" */>}}
{{</code-hl>}}

----

{{< raw wp >}}
The shortcode:
```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: {{< wp OpenBSD >}}
* This other is for Debian: {{< wp Debian >}}
* And, a third more complex: {{< wp "Firewall_(computing)" >}}

## Somewhere

Finally, do not hesitate to have fun with the shortcodes; get help on [the commmunity forum](https://discourse.gohugo.io/).

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



----